com.whitestein.lsps.vaadin.util

Class Variant<T>

java.lang.Object

com.whitestein.lsps.vaadin.util.Variant<T>

Type Parameters:

T - a type of the wrapped value

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

Variant.ClosureVariant, Variant.CollectionVariant, Variant.MapVariant, Variant.RecordVariant

public class Variant<T>
extends Object
implements Serializable

Fluent API for returning record values. Heavily inspired by Guava Optional. Always serializable - will reject objects which are not Serializable nor ValueHolder. It has three reasons to exist:

• Wrap ValueHolder (most importantly its sub-class RecordHolder) into something serializable so that it can be used by Vaadin.
• To hold a value AND its origin (which closure produced the value, which UI component's field did that closure come from, etc).
• Start JTA transaction whenever ValueHolders that might need it are accessed.

To convert a value to a Variant, use:

• one of ofOrigin() or ofUnknownOrigin() if the value is a record,
• wrap(Object, LspsContextHolder) if the value is a general object and the origin is not known,
• the constructor Variant(Object, Type, Origin, LspsContextHolder) if the value is a general object and the origin is known

Immutable. Not equal to the original value - only equal to a Variant of equal value: equals(Object) and hashCode() delegates to valueOrNull().

Author:

mvy

See Also:

Serialized Form

Property Summary

Type	Property and Description
boolean	is Gets the value of the property property.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Variant.ClosureResultOrigin
static class	Variant.ClosureVariant Wraps a closure and forces you to specify the scope in which the closure is executed.
static class	Variant.CollectionVariant<T extends Collection<V>,V> A set variant, allows iterating over collections.
static class	Variant.DereferenceOrigin
static class	Variant.ListVariant<V> A list variant, allows access to list items.
static class	Variant.MapVariant<K,V> A map variant, allows access to map items.
static class	Variant.MethodResultOrigin
static class	Variant.Origin Tracks where variants came from.
static class	Variant.PropertyOrigin
static class	Variant.RecordOrigin
static class	Variant.RecordVariant Accesses RecordHolder properties.
static class	Variant.ReferenceOrigin
static class	Variant.ScopedClosureVariant Wraps a closure and an execution scope.

Field Summary

Fields

Modifier and Type	Field and Description
protected LspsContextHolder	context Context used to serialize the value.
Type	definitionType The defined type of the value, either the record property type, or the closure result type.
static Variant<?>	NULL A variant which wraps the 'null' value, with no origin.
protected Variant.Origin	origin The value origin, such as "ui::Geolocation.latitude".

Constructor Summary

Constructors

Constructor and Description
Variant(T data, Type definitionType, Variant.Origin origin, LspsContextHolder contextHolder) Creates the variant.

Method Summary

Modifier and Type	Method and Description
Variant<Boolean>	bool() Casts the value to boolean.
<N> Variant<N>	cast(Class<N> type) Casts the value.
Variant<T>	checkPresent() Fails if the value is absent.
Variant.ClosureVariant	closure() Casts the value to a closure.
Variant.CollectionVariant<Collection<Object>,Object>	collection() Casts the value to a Collection.
<V> Variant.CollectionVariant<Collection<V>,V>	collectionOf(Class<V> itemType) Casts the value to a Collection.
Variant<Date>	date() Casts the value to Date.
Variant<Decimal>	decimal() Casts the value to a Decimal.
static Variant.RecordVariant	definitionOf(UIComponent component) Returns record variant which accesses given component definition.
static Variant.RecordVariant	definitionOf(UIComponentData data) Returns record variant which accesses given component definition.
Variant<Object>	dereference(UIComponent scope) De-references the referenced type (calls ReferenceHolder.getValue()).
Variant<String>	enumerationConstant() Expects this variant to hold an EnumerationImpl instance.
<E extends Enum<E>> Variant<E>	enumValueOf(Class<E> clazz) Casts this variant to String and then calls Enum.valueOf(Class, String) on the value (if the value is not null).
<E extends Enum<E>> Variant<E>	enumValueOfIgnoreCase(Class<E> clazz) Casts this variant to String and then matches enumeration constant by name, ignoring case differences (if the value is not null).
boolean	equals(Object o)
IllegalStateException	fail(String cause) Throws an IllegalStateException with the following message: "[origin]: invalid value [value]: [cause]".
IllegalStateException	fail(Throwable cause) Throws an IllegalStateException with the following message: "[origin]: invalid value [value]: [cause]".
T	get() Returns the contained instance, which must be present.
Handle	getHandle() Returns a serializable handle for the value of this variant.
Type	getInstanceType() Returns the actual type of the value (or instance).
Variant.Origin	getOrigin() Returns the variant origin, or null if the origin is not known.
boolean	hasHandle() Checks whether getHandle() succeeds (the value is a non-null ValueHolder.
int	hashCode()
boolean	instanceOf(Class<?> valueClass) See Class.isInstance(Object).
Variant<Integer>	integer() Casts the variant's value to a Integer.
boolean	isAbsent() Returns true if the value is null.
boolean	isClosure() Returns true if this variant holds a non-null ClosureHolder.
boolean	isPath() Returns true if this variant holds a non-null Path.
boolean	isPresent() Returns true if this holder contains a (non-null) instance.
boolean	isProperty() Gets the value of the property property.
boolean	isPropertyPath() Deprecated. This method was replaced by isPath() to avoid confusion when one could think this method checks the Variant type to PropertyPath instead of com.whitestein.lsps.lang.exec.Path.
boolean	isRecord() Returns true if this variant holds a non-null RecordHolder.
Variant.ListVariant<Object>	list() Casts the value to a list of objects.
Variant.ListVariant<Object>	listHolder() Casts the value to a ListHolder.
<V> Variant.ListVariant<V>	listOf(Class<V> itemType) Casts the value to a list of objects.
Variant.MapVariant<Object,Object>	map()
Variant.MapVariant<Object,Object>	mapHolder() Casts the value to MapHolder.
<K,V> Variant.MapVariant<K,V>	mapOf(Class<K> keyClass, Class<V> valueClass)
static Variant.RecordVariant	ofOrigin(RecordHolder value, Variant.Origin origin, LspsContextHolder context) Wraps given RecordHolder, with given origin.
static Variant.RecordVariant	ofUnknownOrigin(RecordHolder value, LspsContextHolder context) Wraps given RecordHolder, with no origin.
static Variant.RecordVariant	ofUnknownOrigin(RecordHolder value, UIComponent origin) Wraps given RecordHolder which somehow originated from given component (e.g.
T	or(T defaultValue) Returns the contained instance if it is present; defaultValue otherwise.
Variant<T>	orVariant(T defaultValue) Returns this instance if it is present; a new variant with the defaultValue otherwise.
static <T> Variant<T>	param(T value, String paramName, LspsContextHolder context) Wraps a value which came as a function parameter.
Variant<Path>	path() Casts the variant's value to a Path.
Variant<Property>	property() Casts the variant's value to a Property.
Variant<Path>	propertyPath() Deprecated. This method was replaced by path() to which better fits the type returned.
Variant.RecordVariant	record() Casts the value.
Variant<ReferenceHolder>	reference() Casts the value to a ReferenceHolder.
Variant<T>	requireDefined() Asserts that the definitionType field is present.
SetVariant<Object>	set() Casts the value to a Set.
SetVariant<Object>	setHolder() Casts the value to a SetHolder.
<V> SetVariant<V>	setOf(Class<V> itemType) Casts the value to a Set.
Variant<ReferenceHolder>	setReferencedValue(UIComponent scope, Object newValue) Sets the referenced value to given value.
Variant<ReferenceHolder>	setReferencedValueCollection(UIComponent scope, Collection<?> newValue) Sets the referenced value to given value.
protected void	startTransaction()
Variant<String>	string() Casts the value to String.
Variant<T>	toNull() Creates a new variant of same type and origin, but with null value.
String	toString()
Variant<String>	toUpperCase() First casts the value to string, then calls String.toUpperCase() and returns variant holding such string.
Variant<T>	toValue(T newValue) Creates a new variant of same type and origin, but with given value.
T	valueOrNull() Returns the contained instance if it is present; null otherwise.
static <T> Variant<T>	wrap(T data, LspsContextHolder context) Wraps given object in a variant, making it effectively serializable.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Property Detail

is

public boolean isProperty

Gets the value of the property property.

Field Detail

NULL

public static final Variant<?> NULL

A variant which wraps the 'null' value, with no origin.

definitionType

public final Type definitionType

The defined type of the value, either the record property type, or the closure result type. May be null: see requireDefined().

Take care when using this value: for example, the source field may be of type SimpleType.OBJECT while the instance is in fact of type ClosureType.

origin

protected final Variant.Origin origin

The value origin, such as "ui::Geolocation.latitude".

context

protected final LspsContextHolder context

Context used to serialize the value.

Constructor Detail

Variant

public Variant(T data,
               Type definitionType,
               Variant.Origin origin,
               LspsContextHolder contextHolder)

Creates the variant.

Parameters:

data - the value, may be null.

definitionType - The type of the value, either the record property type, or the closure result type. null: see requireDefined().

origin - The value origin, such as "ui::Geolocation.latitude". Must not be null.

contextHolder - used to serialize ValueHolders. May be null in very special cases when the Variant serialization will not be performed.

Method Detail

getHandle

public Handle getHandle()

Returns a serializable handle for the value of this variant. The value must be a non-null ValueHolder - if not, this function fails.

Returns:

a non-null handle for a value holder instance, never null.

Throws:

IllegalStateException - if the value is null or is not a ValueHolder

hasHandle

public boolean hasHandle()

Checks whether getHandle() succeeds (the value is a non-null ValueHolder.

Returns:

true if getHandle() succeeds and returns a non-null value, false if getHandle() throws IllegalStateException.

getInstanceType

public Type getInstanceType()

Returns the actual type of the value (or instance). In case of a non-null Decimal instance, consults definitionType to differentiate between DecimalType and IntegerType.

Returns:

the actual type of the value. Returns SimpleType.NULL when absent.

wrap

public static <T> Variant<T> wrap(T data,
                                  LspsContextHolder context)

Wraps given object in a variant, making it effectively serializable. Serves as a replacement for UIComponents.wrap(Object, com.whitestein.lsps.vaadin.LspsContextHolder)

Type Parameters:

T - the object type

Parameters:

data - the object, may be null. Must be either serializable, or a value holder.

context - the context, not null

Returns:

non-null variant

isPresent

public boolean isPresent()

Returns true if this holder contains a (non-null) instance.

Returns:

true if present, false if absent (null).

checkPresent

public Variant<T> checkPresent()

Fails if the value is absent.

Returns:

this

Throws:

IllegalStateException - if the value is absent (value is null)

definitionOf

public static Variant.RecordVariant definitionOf(UIComponent component)

Returns record variant which accesses given component definition.

Parameters:

component - the component, not null.

Returns:

the variant, never null. Always present.

definitionOf

public static Variant.RecordVariant definitionOf(UIComponentData data)

Returns record variant which accesses given component definition.

Parameters:

data - the component data, not null.

Returns:

the variant, never null. Always present.

cast

public <N> Variant<N> cast(Class<N> type)

Casts the value. Fails if the value can not be cast to given type. Never fails if the variant is absent.

Type Parameters:

N - the target type

Parameters:

type - the target type, not null.

Returns:

variant of given type, holding the very same value, but cast. Never null.

Throws:

IllegalStateException - if the value is not of required type.

bool

public Variant<Boolean> bool()

Casts the value to boolean. Fails if the value can not be cast to given type. Never fails if the variant is absent.

Returns:

variant of type boolean, never null.

Throws:

IllegalStateException - if the value is not Boolean.

string

public Variant<String> string()

Casts the value to String. Fails if the value can not be cast to given type. Never fails if the variant is absent.

Returns:

variant of type String, never null.

Throws:

IllegalStateException - if the value is not String.

date

public Variant<Date> date()

Casts the value to Date. Fails if the value can not be cast to given type. Never fails if the variant is absent.

Returns:

variant of type Date, never null.

Throws:

IllegalStateException - if the value is not Date.

valueOrNull

public T valueOrNull()

Returns the contained instance if it is present; null otherwise. If the instance is known to be present, use get() instead.

Returns:

the value, may be null.

get

public T get()

Returns the contained instance, which must be present. If the instance might be absent, use or(Object) or valueOrNull() instead.

Returns:

non-null value.

Throws:

IllegalStateException - if the value is null.

fail

public final IllegalStateException fail(String cause)

Throws an IllegalStateException with the following message: "[origin]: invalid value [value]: [cause]". Never returns normally.

To satisfy the compiler, use as follows: throw fail("must be 3..5").

Parameters:

cause - the cause, not null.

Returns:

IllegalStateException

fail

public final IllegalStateException fail(Throwable cause)

Throws an IllegalStateException with the following message: "[origin]: invalid value [value]: [cause]". Never returns normally.

To satisfy the compiler, use as follows: throw fail("must be 3..5").

Parameters:

cause - the cause, not null.

Returns:

IllegalStateException

or

public T or(T defaultValue)

Returns the contained instance if it is present; defaultValue otherwise. If no default value should be required because the instance is known to be present, use get() instead. For a default value of null, use valueOrNull().

Parameters:

defaultValue - the default value, may be null.

Returns:

the value or the default value if the value is null.

orVariant

public Variant<T> orVariant(T defaultValue)

Returns this instance if it is present; a new variant with the defaultValue otherwise. If no default value should be required because the instance is known to be present, use get() instead. For a default value of null, use valueOrNull().

Parameters:

defaultValue - the default value, may be null.

Returns:

the value or the default value if the value is null.

record

public Variant.RecordVariant record()

Casts the value. Fails if the value can not be cast to given type. Never fails if the variant is absent.

Returns:

variant of given type, never null.

Throws:

IllegalStateException - if the value is not RecordHolder.

closure

public Variant.ClosureVariant closure()

Casts the value to a closure. Fails if the value can not be cast to a closure. Never fails if the variant is absent.

Returns:

variant holding a closure, never null.

toUpperCase

public Variant<String> toUpperCase()

First casts the value to string, then calls String.toUpperCase() and returns variant holding such string. If the value is absent, a variant holding null is returned.

Returns:

a string variant with the string turned upcase, never null.

enumValueOf

public <E extends Enum<E>> Variant<E> enumValueOf(Class<E> clazz)

Casts this variant to String and then calls Enum.valueOf(Class, String) on the value (if the value is not null).

Type Parameters:

E - the enum type

Parameters:

clazz - the enum class, not null.

Returns:

variant holding value of given enum, never null. Absent if this variant is absent.

Throws:

IllegalStateException - if the variant is not string or there is no such enum constant in the

enumValueOfIgnoreCase

public <E extends Enum<E>> Variant<E> enumValueOfIgnoreCase(Class<E> clazz)

Casts this variant to String and then matches enumeration constant by name, ignoring case differences (if the value is not null).

Type Parameters:

E - the enum type

Parameters:

clazz - the enum class, not null.

Returns:

variant holding value of given enum, never null. Absent if this variant is absent.

Throws:

IllegalStateException - if the variant is not string or there is no such enum constant in the

ofUnknownOrigin

public static Variant.RecordVariant ofUnknownOrigin(RecordHolder value,
                                                    UIComponent origin)

Wraps given RecordHolder which somehow originated from given component (e.g. an ApplicationEvent record instance, created when a button is clicked).

Parameters:

value - the record, may be null

origin - the originating component, not null.

Returns:

the variant wrapping given record, never null.

ofUnknownOrigin

public static Variant.RecordVariant ofUnknownOrigin(RecordHolder value,
                                                    LspsContextHolder context)

Wraps given RecordHolder, with no origin. Given context is used when the record is serialized.

Parameters:

value - the record holder, may be null.

context - the context. If null, the serialization will fail!

Returns:

variant, wrapping given record, never null.

param

public static <T> Variant<T> param(T value,
                                   String paramName,
                                   LspsContextHolder context)

Wraps a value which came as a function parameter.

Type Parameters:

T - the value type

Parameters:

value - the value, may be null

paramName - the parameter name, not null

context - context, may be null ONLY if this variant is not going to be serialized.

Returns:

variant, never null.

startTransaction

protected void startTransaction()

ofOrigin

public static Variant.RecordVariant ofOrigin(RecordHolder value,
                                             Variant.Origin origin,
                                             LspsContextHolder context)

Wraps given RecordHolder, with given origin. Given context is used when the record is serialized.

Parameters:

value - the record holder, may be null.

origin - the origin of the value

context - the context. If null, the serialization will fail!

Returns:

variant, wrapping given record, never null.

enumerationConstant

public Variant<String> enumerationConstant()

Expects this variant to hold an EnumerationImpl instance. Returns the enumeration constant. Returns an absent variant if this variant is absent.

Returns:

enumeration constant variant, never null.

property

public Variant<Property> property()

Casts the variant's value to a Property. Fails if the value can not be cast to given type. Never fails if the variant is absent.

Returns:

a variant, holding the very same value, but cast to Property.

Throws:

IllegalStateException - if the value is not of required type.

propertyPath

@Deprecated
public Variant<Path> propertyPath()

Deprecated. This method was replaced by path() to which better fits the type returned.

Casts the variant's value to a Path. Fails if the value can not be cast to given type. Never fails if the variant is absent.

Returns:

a variant, holding the very same value, but cast to Path.

Throws:

IllegalStateException - if the value is not of required type.

path

public Variant<Path> path()

Casts the variant's value to a Path. Fails if the value can not be cast to given type. Never fails if the variant is absent.

Returns:

a variant, holding the very same value, but cast to Path.

Throws:

IllegalStateException - if the value is not of required type.

isClosure

public boolean isClosure()

Returns true if this variant holds a non-null ClosureHolder.

Returns:

true if this is a closure.

isProperty

public boolean isProperty()

Gets the value of the property property.

isPropertyPath

@Deprecated
public boolean isPropertyPath()

Deprecated. This method was replaced by isPath() to avoid confusion when one could think this method checks the Variant type to PropertyPath instead of com.whitestein.lsps.lang.exec.Path.

Returns true if this variant holds a non-null Path.

Returns:

true if this is a non-null path

isPath

public boolean isPath()

Returns true if this variant holds a non-null Path.

Returns:

true if this is a non-null path

getOrigin

public Variant.Origin getOrigin()

Returns the variant origin, or null if the origin is not known.

Returns:

variant origin, may be null.

integer

public Variant<Integer> integer()

Casts the variant's value to a Integer. Fails if the value can not be cast to given type. Never fails if the variant is absent.

Returns:

a variant, holding the very same value, but cast to Integer.

Throws:

IllegalStateException - if the value is not of required type.

isRecord

public boolean isRecord()

Returns true if this variant holds a non-null RecordHolder.

Returns:

true if this is a non-null record.

decimal

public Variant<Decimal> decimal()

Casts the value to a Decimal. Fails if the value can not be cast to the Decimal. Never fails if the variant is absent.

Returns:

variant holding a Decimal, never null.

Throws:

IllegalStateException - if the value is not of required type.

reference

public Variant<ReferenceHolder> reference()

Casts the value to a ReferenceHolder. Fails if the value can not be cast to the ReferenceHolder. Never fails if the variant is absent.

Returns:

variant holding a ReferenceHolder, never null.

Throws:

IllegalStateException - if the value is not of required type.

toString

public String toString()

Overrides:

toString in class Object

dereference

public Variant<Object> dereference(UIComponent scope)

De-references the referenced type (calls ReferenceHolder.getValue()). Returns null value if reference itself is null.

Parameters:

scope - the scope component, not null.

Returns:

never null Variant. Variant value is null when the reference itself is null or the reference references a null value.

Throws:

IllegalStateException - if the value is not ReferenceHolder.

setReferencedValue

public Variant<ReferenceHolder> setReferencedValue(UIComponent scope,
                                                   Object newValue)

Sets the referenced value to given value. Fails if this variant does not hold a reference. Fails if the reference is null (absent).

Parameters:

scope - the scope component, not null.

newValue - the new value, may be null.

Returns:

variant of type ReferenceHolder, this.

setReferencedValueCollection

public Variant<ReferenceHolder> setReferencedValueCollection(UIComponent scope,
                                                             Collection<?> newValue)

Sets the referenced value to given value. Fails if this variant does not hold a reference. Fails if the reference is null (absent). Expects the reference to refer a collection type. Creates a compatible type (Set or List), depending on the current value of the reference and/or the referred type.

Parameters:

scope - the scope component, not null.

newValue - the new value, may be null.

Returns:

variant of type ReferenceHolder, this.

requireDefined

public Variant<T> requireDefined()

Asserts that the definitionType field is present. If the field is null, this may be caused by closure being null, or the field not defined in the record.

Returns:

this

setHolder

public SetVariant<Object> setHolder()

Casts the value to a SetHolder. Fails if the value can not be cast to the SetHolder. Never fails if the variant is absent.

Returns:

variant holding a SetHolder, never null.

Throws:

IllegalStateException - if the value is not of required type.

set

public SetVariant<Object> set()

Casts the value to a Set. Fails if the value can not be cast to the Set. Never fails if the variant is absent.

Returns:

variant holding a Set, never null.

Throws:

IllegalStateException - if the value is not of required type.

setOf

public <V> SetVariant<V> setOf(Class<V> itemType)

Casts the value to a Set. Fails if the value can not be cast to the Set. Never fails if the variant is absent.

Type Parameters:

V -

Parameters:

itemType - all items are required to be of given type.

Returns:

variant holding a Set, never null.

Throws:

IllegalStateException - if the value is not of required type.

collectionOf

public <V> Variant.CollectionVariant<Collection<V>,V> collectionOf(Class<V> itemType)

Casts the value to a Collection. Fails if the value can not be cast to the Collection. Never fails if the variant is absent.

Type Parameters:

V -

Parameters:

itemType - all items are required to be of given type.

Returns:

variant holding a Collection, never null.

Throws:

IllegalStateException - if the value is not of required type.

collection

public Variant.CollectionVariant<Collection<Object>,Object> collection()

Casts the value to a Collection. Fails if the value can not be cast to the Collection. Never fails if the variant is absent.

Returns:

variant holding a Collection, never null.

Throws:

IllegalStateException - if the value is not of required type.

listHolder

public Variant.ListVariant<Object> listHolder()

Casts the value to a ListHolder. Fails if the value can not be cast to the ListHolder. Never fails if the variant is absent.

Returns:

variant holding a ListHolder, never null.

Throws:

IllegalStateException - if the value is not of required type.

list

public Variant.ListVariant<Object> list()

Casts the value to a list of objects.

Returns:

a variant containing list of objects, never null.

listOf

public <V> Variant.ListVariant<V> listOf(Class<V> itemType)

Casts the value to a list of objects.

Returns:

a variant containing list of objects, never null.

map

public Variant.MapVariant<Object,Object> map()

mapOf

public <K,V> Variant.MapVariant<K,V> mapOf(Class<K> keyClass,
                                           Class<V> valueClass)

mapHolder

public Variant.MapVariant<Object,Object> mapHolder()

Casts the value to MapHolder.

Returns:

a variant containing a map holder, never null.

instanceOf

public boolean instanceOf(Class<?> valueClass)

See Class.isInstance(Object).

Parameters:

valueClass - the expected class, not null.

Returns:

true if the value is not null and can be cast to valueClass, false otherwise.

isAbsent

public boolean isAbsent()

Returns true if the value is null.

Returns:

true if the value is null, false if it is a non-null value.

toNull

public Variant<T> toNull()

Creates a new variant of same type and origin, but with null value.

Returns:

a new variant, never null.

toValue

public Variant<T> toValue(T newValue)

Creates a new variant of same type and origin, but with given value.

Parameters:

newValue - the new value, may be null.

Returns:

a new variant, never null.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object