org.simantics.databoard
Class Bindings

java.lang.Object
  extended by org.simantics.databoard.Bindings

public class Bindings
extends java.lang.Object

This ia a facade class for the binding services.

Author:
Toni Kalajainen

Field Summary
static AdapterFactory adapterFactory
           
static BooleanBinding BOOLEAN
           
static ArrayBinding BOOLEAN_ARRAY
           
static ByteBinding BYTE
           
static ArrayBinding BYTE_ARRAY
           
static BindingFactory defaultBindingFactory
           
static java.util.Map<Datatype,Binding> defaultBindingRepository
           
static SerializerFactory defaultSerializationFactory
           
static DoubleBinding DOUBLE
           
static ArrayBinding DOUBLE_ARRAY
           
static FloatBinding FLOAT
           
static ArrayBinding FLOAT_ARRAY
           
static ArrayBinding INT_ARRAY
           
static IntegerBinding INTEGER
           
static LongBinding LONG
           
static ArrayBinding LONG_ARRAY
           
static BooleanBinding MUTABLE_BOOLEAN
           
static ByteBinding MUTABLE_BYTE
           
static DoubleBinding MUTABLE_DOUBLE
           
static FloatBinding MUTABLE_FLOAT
           
static IntegerBinding MUTABLE_INTEGER
           
static LongBinding MUTABLE_LONG
           
static StringBinding MUTABLE_STRING
           
static ByteBinding MUTABLE_UNSIGNED_BYTE
           
static IntegerBinding MUTABLE_UNSIGNED_INTEGER
           
static LongBinding MUTABLE_UNSIGNED_LONG
           
static VariantBinding MUTABLE_VARIANT
           
static BindingFactory mutableBindingFactory
           
static java.util.Map<Datatype,Binding> mutableBindingRepository
           
static ObjectVariantBinding OBJECT
           
static ReflectionBindingFactory reflectionBindingFactory
           
static java.util.Map<BindingRequest,Binding> reflectionBindingRepository
           
static java.util.Map<Binding,Serializer> serializerRepository
           
static VariantBinding STR_VARIANT
           
static StringBinding STRING
           
static ArrayBinding STRING_ARRAY
           
static ByteBinding UNSIGNED_BYTE
           
static IntegerBinding UNSIGNED_INTEGER
           
static LongBinding UNSIGNED_LONG
           
static VariantBinding VARIANT
           
 
Constructor Summary
Bindings()
           
 
Method Summary
static java.lang.Object adapt(java.lang.Object value, Binding domain, Binding range)
          Adapt a value of one type to another.
static java.lang.Object adaptUnchecked(java.lang.Object value, Binding domain, Binding range)
          Adapt a value of one type to another
static java.lang.Object clone(java.lang.Object value, Binding domain, Binding range)
          Clone a value to another type to another.
static java.lang.Object cloneUnchecked(java.lang.Object value, Binding domain, Binding range)
          Clone a value of one binding to another.
static int compare(Binding b1, java.lang.Object o1, Binding b2, java.lang.Object o2)
          Compares its two data values for order.
static java.util.Comparator<java.lang.Object> createComparator(Binding b1, Binding b2)
           
static boolean equals(Binding b1, java.lang.Object o1, Binding b2, java.lang.Object o2)
          Compare two data values for equality.
static Adapter getAdapter(Binding domain, Binding range)
          Create an adapter that adapts two bindings of the same data type.
static Adapter getAdapterUnchecked(Binding domain, Binding range)
          Create an adapter that adapts between two bindings of the same data type.
static
<T extends Binding>
T
getBinding(java.lang.Class<?> clazz)
          Get a binding to a Java Class.
static
<T extends Binding>
T
getBinding(java.lang.Class<?> clazz, java.lang.Class<?>... parameters)
          Get a binding to a Java Class.
static
<T extends Binding>
T
getBinding(Datatype type)
          Get a binding that uses default java classes, such as Integer.class, or byte[].class.
static
<T extends Binding>
T
getBindingUnchecked(java.lang.Class<?> clazz)
          Read binding and type from a class.
static
<T extends Binding>
T
getMutableBinding(Datatype type)
          Get a binding to a DataType that is completely mutable java class.
static Serializer getSerializer(Binding binding)
          Get serializer that follows Databoard serialization spec.
static Serializer getSerializer(java.lang.Class<?> clazz)
          Get serializer that follows Databoard serialization spec.
static Serializer getSerializerUnchecked(Binding binding)
          Get serializer that follows Databoard serialization spec.
static Serializer getSerializerUnchecked(java.lang.Class<?> clazz)
          Get serializer that follows Databoard serialization spec.
static Adapter getTypeAdapter(Binding domain, Binding range)
          Create a type adapter that adapts instances from one DataType to another.
static Adapter getTypeAdapterUnchecked(Binding domain, Binding range)
          Create a type adapter that adapts instances from one DataType to another.
static java.lang.String toString(java.lang.Object o)
          Print the content of an object as a structure.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mutableBindingRepository

public static final java.util.Map<Datatype,Binding> mutableBindingRepository

defaultBindingRepository

public static final java.util.Map<Datatype,Binding> defaultBindingRepository

reflectionBindingRepository

public static final java.util.Map<BindingRequest,Binding> reflectionBindingRepository

serializerRepository

public static final java.util.Map<Binding,Serializer> serializerRepository

mutableBindingFactory

public static final BindingFactory mutableBindingFactory

defaultBindingFactory

public static final BindingFactory defaultBindingFactory

reflectionBindingFactory

public static final ReflectionBindingFactory reflectionBindingFactory

defaultSerializationFactory

public static final SerializerFactory defaultSerializationFactory

adapterFactory

public static final AdapterFactory adapterFactory

STRING

public static final StringBinding STRING

INTEGER

public static final IntegerBinding INTEGER

BOOLEAN

public static final BooleanBinding BOOLEAN

BYTE

public static final ByteBinding BYTE

LONG

public static final LongBinding LONG

DOUBLE

public static final DoubleBinding DOUBLE

FLOAT

public static final FloatBinding FLOAT

OBJECT

public static final ObjectVariantBinding OBJECT

VARIANT

public static final VariantBinding VARIANT

STR_VARIANT

public static final VariantBinding STR_VARIANT

BOOLEAN_ARRAY

public static final ArrayBinding BOOLEAN_ARRAY

BYTE_ARRAY

public static final ArrayBinding BYTE_ARRAY

INT_ARRAY

public static final ArrayBinding INT_ARRAY

LONG_ARRAY

public static final ArrayBinding LONG_ARRAY

FLOAT_ARRAY

public static final ArrayBinding FLOAT_ARRAY

DOUBLE_ARRAY

public static final ArrayBinding DOUBLE_ARRAY

STRING_ARRAY

public static final ArrayBinding STRING_ARRAY

UNSIGNED_INTEGER

public static final IntegerBinding UNSIGNED_INTEGER

UNSIGNED_BYTE

public static final ByteBinding UNSIGNED_BYTE

UNSIGNED_LONG

public static final LongBinding UNSIGNED_LONG

MUTABLE_STRING

public static final StringBinding MUTABLE_STRING

MUTABLE_INTEGER

public static final IntegerBinding MUTABLE_INTEGER

MUTABLE_BOOLEAN

public static final BooleanBinding MUTABLE_BOOLEAN

MUTABLE_BYTE

public static final ByteBinding MUTABLE_BYTE

MUTABLE_LONG

public static final LongBinding MUTABLE_LONG

MUTABLE_FLOAT

public static final FloatBinding MUTABLE_FLOAT

MUTABLE_DOUBLE

public static final DoubleBinding MUTABLE_DOUBLE

MUTABLE_VARIANT

public static final VariantBinding MUTABLE_VARIANT

MUTABLE_UNSIGNED_INTEGER

public static final IntegerBinding MUTABLE_UNSIGNED_INTEGER

MUTABLE_UNSIGNED_BYTE

public static final ByteBinding MUTABLE_UNSIGNED_BYTE

MUTABLE_UNSIGNED_LONG

public static final LongBinding MUTABLE_UNSIGNED_LONG
Constructor Detail

Bindings

public Bindings()
Method Detail

getMutableBinding

public static <T extends Binding> T getMutableBinding(Datatype type)
Get a binding to a DataType that is completely mutable java class. DataType | Class of the bound instance ===================|================== UnionType | GenericBinding.TaggedObject.class OptionType | ValueContainer.class RecordType | Object[].class BooleanType | MutableBoolean.class DoubleType | MutableDouble.class FloatType | MutableFloat.class ByteType | MutableByte.class IntegerType | MutableInt.class LongType | MutableLong.class StringType | ValueContainer.class ArrayType | ArrayList.class MapType | TreeMap.class VariantType | MutableVariant.class Note, requesting a binding with this convenience method stores the binding and the type with strong reference, thus preventing garbage collection. To allow garbage collection, please use another instance of GenericBindingFactory and binding repository (Map).

Parameters:
type -
Returns:
binding binding to a mutable class

getBinding

public static <T extends Binding> T getBinding(Datatype type)
Get a binding that uses default java classes, such as Integer.class, or byte[].class. The result is almost always immutable. This method is more efficient than generic bindings (above). BooleanType | Boolean.class ByteType | Byte.class FloatType | Float.class DoubleType | Double.class IntegerType | Int.class LongType | Long.class StringType | String.class UnionType | TaggedObject.class OptionType | ValueContainer.class RecordType | Object[].class MapType | TreeMap.class VariantType | Variant.class ArrayType(Boolean) | boolean[].class ArrayType(Byte) | byte[].class ArrayType(Integer) | int[].class ArrayType(Long) | long[].class ArrayType(Float) | float[].class ArrayType(Double) | double[].class ArrayType(Byte) | byte[].class ArrayType( T ) | Object[].class Note, requesting a binding with this convenience method stores the binding and the type with strong reference, thus preventing garbage collection. To allow garbage collection, please use another instance of DefaultBindingFactory and binding repository (Map).

Parameters:
type -
Returns:
binding binding to a mutable class

getBinding

public static <T extends Binding> T getBinding(java.lang.Class<?> clazz)
                                    throws BindingConstructionException
Get a binding to a Java Class. Type details can be modified with annotations. Please see the package org.simantics.databoard.annotations.

The whether the result binding is a completely mutable or not depends on the provided classes. For instance, fields such as Boolean, Integer, Long are not mutable, instead MutableBoolean, MutableInteger and MutableLong are. The length of Object[] is not mutable, but length of List is.

Note, requesting a binding with this convenience method stores the binding and the class with strong reference, thus preventing garbage collection. To allow garbage collection, please use another instance of BindingFactory and binding repository (Map).

Parameters:
clazz -
Returns:
binding
Throws:
BindingConstructionException
See Also:
ReflectionBindingFactory

getBinding

public static <T extends Binding> T getBinding(java.lang.Class<?> clazz,
                                               java.lang.Class<?>... parameters)
                                    throws BindingConstructionException
Get a binding to a Java Class. Use this method to acquire class parameters for a generics class.

Example 1: Binding binding = Bindings.getBinding(Map.class, String.class, Integer.class); Map map = (Map) binding.createDefault(); Example 2: Binding d = Bindings.getBinding(List.class, Integer.class); List list = (List) d.createRandom(5); Example 3: Binding d = Bindings.getBinding(List.class, List.class, Integer.class); List> list = (List>) d.createRandom(5);

Parameters:
clazz -
Returns:
binding
Throws:
BindingConstructionException
See Also:
ReflectionBindingFactory

getBindingUnchecked

public static <T extends Binding> T getBindingUnchecked(java.lang.Class<?> clazz)
                                             throws RuntimeBindingConstructionException
Read binding and type from a class. DataType details and parameters are read as annotations placed in the class. (See org.simantics.databoard.annotations)

As an exception, in the subclasses of Throwable, the fields of Throwable are omited.

This method is used when the caller is 100% sure that binding will be constructed without exceptions. Such classes are all primitive types (Double, Integer, etc, arrays, DataType, ...) This method is unchecked if binding construction to the clazz cannot be trusted. If construction fails, a RuntimeException is thrown.

Parameters:
clazz -
Returns:
binding
Throws:
RuntimeBindingConstructionException

getSerializer

public static Serializer getSerializer(Binding binding)
                                throws SerializerConstructionException
Get serializer that follows Databoard serialization spec.

Parameters:
binding -
Returns:
serializer
Throws:
SerializerConstructionException

getSerializerUnchecked

public static Serializer getSerializerUnchecked(Binding binding)
                                         throws RuntimeSerializerConstructionException
Get serializer that follows Databoard serialization spec.

Parameters:
binding -
Returns:
serializer
Throws:
RuntimeSerializerConstructionException

getSerializer

public static Serializer getSerializer(java.lang.Class<?> clazz)
                                throws SerializerConstructionException
Get serializer that follows Databoard serialization spec.

Parameters:
clazz -
Returns:
serializer
Throws:
SerializerConstructionException

getSerializerUnchecked

public static Serializer getSerializerUnchecked(java.lang.Class<?> clazz)
                                         throws RuntimeSerializerConstructionException
Get serializer that follows Databoard serialization spec.

Parameters:
clazz -
Returns:
serializer serializer
Throws:
RuntimeSerializerConstructionException

getAdapter

public static Adapter getAdapter(Binding domain,
                                 Binding range)
                          throws AdapterConstructionException
Create an adapter that adapts two bindings of the same data type.

Parameters:
domain - binding of the source instance
range - binding of the result instance
Returns:
result adapter
Throws:
AdapterConstructionException

getAdapterUnchecked

public static Adapter getAdapterUnchecked(Binding domain,
                                          Binding range)
                                   throws RuntimeAdapterConstructionException
Create an adapter that adapts between two bindings of the same data type.

Parameters:
domain - binding of the source instance
range - binding of the result instance
Returns:
result adapter
Throws:
AdapterConstructionException
RuntimeAdapterConstructionException

getTypeAdapter

public static Adapter getTypeAdapter(Binding domain,
                                     Binding range)
                              throws AdapterConstructionException
Create a type adapter that adapts instances from one DataType to another. Type Adapter does the following conversions: o Number Types, e.g. long -> double o Unit Types, e.g. mph -> km/h o Record Types, for each field of the range, there must be equal in domain o Union Types, for each tag type of the domain, there must be equal in range AdaptException is thrown at runtime, if number values are not compatible, e.g. converting value 500 from Long to Byte. Note, there is also a possibility of precision loss, e.g. when converting from double to int.

Parameters:
domain - binding of the source instance
range - binding of the result instance
Returns:
result adapter
Throws:
AdapterConstructionException

getTypeAdapterUnchecked

public static Adapter getTypeAdapterUnchecked(Binding domain,
                                              Binding range)
Create a type adapter that adapts instances from one DataType to another. Type Adapter does the following conversions: o Number Types, e.g. long -> double o Unit Types, e.g. mph -> km/h o Record Types, for each field of the range, there must be equal in domain o Union Types, for each tag type of the domain, there must be equal in range AdaptException is thrown at runtime, if number values are not compatible, e.g. converting value 500 from Long to Byte. Note, there is also a possibility of precision loss, e.g. when converting from double to int.

Parameters:
domain - binding of the source instance
range - binding of the result instance
Returns:
result adapter
Throws:
AdapterConstructionException

adapt

public static java.lang.Object adapt(java.lang.Object value,
                                     Binding domain,
                                     Binding range)
                              throws AdaptException
Adapt a value of one type to another.

Parameters:
value -
domain -
range -
Returns:
adapted value
Throws:
AdapterConstructionException
AdaptException

adaptUnchecked

public static java.lang.Object adaptUnchecked(java.lang.Object value,
                                              Binding domain,
                                              Binding range)
                                       throws RuntimeAdapterConstructionException,
                                              RuntimeAdaptException
Adapt a value of one type to another

Parameters:
value -
domain -
range -
Returns:
adapted value
Throws:
AdapterConstructionException
AdaptException
RuntimeAdapterConstructionException
RuntimeAdaptException

clone

public static java.lang.Object clone(java.lang.Object value,
                                     Binding domain,
                                     Binding range)
                              throws AdaptException
Clone a value to another type to another. Bindings that handle immutable values may return the same instance, others will guarantee a complete copy.

Parameters:
value -
domain -
range -
Returns:
adapted value
Throws:
AdapterConstructionException
AdaptException

cloneUnchecked

public static java.lang.Object cloneUnchecked(java.lang.Object value,
                                              Binding domain,
                                              Binding range)
                                       throws RuntimeAdapterConstructionException,
                                              RuntimeAdaptException
Clone a value of one binding to another. Bindings that handle immutable values may return the same instance, others will guarantee a complete copy.

Parameters:
value -
domain -
range -
Returns:
adapted value
Throws:
AdapterConstructionException
AdaptException
RuntimeAdapterConstructionException
RuntimeAdaptException

compare

public static int compare(Binding b1,
                          java.lang.Object o1,
                          Binding b2,
                          java.lang.Object o2)
                   throws BindingException
Compares its two data values for order. Returns a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.

DataTypes of b1 and b2 are not equal then data types are compared.

The comparison function is defined at http://dev.simantics.org/index.php/Org.simantics.datatype_Manual#CompareTo_and_Equals

Note, comparing 2 different number types will not result a value comparison. Instead values have the following type precedence ByteType, IntegerType, LongType, FloatType, and the highest DoubleType.

Parameters:
b1 - Binding of o1
o1 - the first object to be compared.
b2 - Binding of o2
o2 - the second object to be compared.
Returns:
a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.
Throws:
BindingException - if object cannot be handled by a binding

equals

public static boolean equals(Binding b1,
                             java.lang.Object o1,
                             Binding b2,
                             java.lang.Object o2)
                      throws BindingException
Compare two data values for equality.

Note, comparing 2 different number types will not result a value comparison. Instead values have the following type precedence ByteType, IntegerType, LongType, FloatType, and the highest DoubleType.

Parameters:
b1 -
o1 -
b2 -
o2 -
Returns:
true if equal
Throws:
BindingException

createComparator

public static java.util.Comparator<java.lang.Object> createComparator(Binding b1,
                                                                      Binding b2)

toString

public static java.lang.String toString(java.lang.Object o)
Print the content of an object as a structure. Utility function for debug purposes.

Parameters:
o -
Returns:
content