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
          Adapter Factory
static Binding BEAN
           
static BindingRepository bindingRepository
          Repository of class Bindings
static BooleanBinding BOOLEAN
           
static ArrayBinding BOOLEAN_ARRAY
           
static ByteBinding BYTE
           
static ArrayBinding BYTE_ARRAY
           
static ClassBindingFactory classBindingFactory
          Reflection based Binding Factory, create binding to class
static Databoard databoard
           
static TypeBindingFactory defaultBindingFactory
          Default Bindings Factory
static java.util.Map<Datatype,Binding> defaultBindingRepository
          Repository of default bindings
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 TypeBindingFactory mutableBindingFactory
          Mutable Bindings Factory
static java.util.Map<Datatype,Binding> mutableBindingRepository
          Repository of mutable bindings
static VariantBinding OBJECT
           
static SerializerFactory serializationFactory
          Serializer Factory
static java.util.Map<Binding,Serializer> serializerRepository
          Repository of serializers
static VariantBinding STR_VARIANT
           
static StringBinding STRING
           
static ArrayBinding STRING_ARRAY
           
static TypeClassFactory typeClassFactory
          Class Factory
static ByteBinding UNSIGNED_BYTE
           
static IntegerBinding UNSIGNED_INTEGER
           
static LongBinding UNSIGNED_LONG
           
static VariantBinding VARIANT
           
static Binding VOID
           
 
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 void addBinding(Binding binding, java.lang.Class<?> clazz, java.lang.Class<?>... parameters)
          Add a simple binding to reflection binding factory.
static void addBindingFactory(BindingSubFactory factory)
          Add binding factory for compositive bindings
static java.lang.Object clone(java.lang.Object value, Binding domain, Binding range)
          Adapt and clone a value instance to another type.
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 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 Binding getBeanBinding(Datatype type)
          Create binding from datatype that instantiates java classes.
static BindingRequest getBeanBindingRequest(Datatype type)
          Creates a bean class
static java.lang.Class<?> getBeanClass(Datatype type)
          Creates a bean class
static
<T extends Binding>
T
getBinding(BindingRequest request)
           
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 for a Java Class.
static
<T extends Binding>
T
getBinding(Datatype type)
          Get or create a binding based on 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
getBindingUnchecked(java.lang.Class<?> clazz, java.lang.Class<?>... parameters)
          Get a binding for a Java Class.
static
<T extends Binding>
T
getMutableBinding(Datatype type)
          Get or create a binding 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

databoard

public static final Databoard databoard

mutableBindingRepository

public static final java.util.Map<Datatype,Binding> mutableBindingRepository
Repository of mutable bindings


defaultBindingRepository

public static final java.util.Map<Datatype,Binding> defaultBindingRepository
Repository of default bindings


bindingRepository

public static final BindingRepository bindingRepository
Repository of class Bindings


serializerRepository

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


mutableBindingFactory

public static final TypeBindingFactory mutableBindingFactory
Mutable Bindings Factory


defaultBindingFactory

public static final TypeBindingFactory defaultBindingFactory
Default Bindings Factory


classBindingFactory

public static final ClassBindingFactory classBindingFactory
Reflection based Binding Factory, create binding to class


serializationFactory

public static final SerializerFactory serializationFactory
Serializer Factory


adapterFactory

public static final AdapterFactory adapterFactory
Adapter Factory


typeClassFactory

public static final TypeClassFactory typeClassFactory
Class Factory


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

VARIANT

public static final VariantBinding VARIANT

OBJECT

public static final VariantBinding OBJECT

STR_VARIANT

public static final VariantBinding STR_VARIANT

VOID

public static final Binding VOID

BEAN

public static final Binding BEAN

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

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

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_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 or create a binding 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 - the type to create binding to
Returns:
binding binding to a mutable class

getBinding

public static <T extends Binding> T getBinding(Datatype type)
Get or create a binding based on default java classes, such as Integer.class, or byte[].class. The result is often binding for an immutable classs. These bindings are more efficient than mutable bindings (above). DataType | Class of the bound instance ===================|================== 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 - the type to create binding to
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. Details can be added by placing annotations to the java classes. See more in package org.simantics.databoard.annotations.

Whether the result is a completely mutable or not depends on the requested class. 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).

Is asm library is available, the binding is bytecode generated. Then read and write operations are direct get/set calls or direct field read/writes. There is no reflection used.

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

getBinding

public static <T extends Binding> T getBinding(BindingRequest request)
                                    throws BindingConstructionException
Throws:
BindingConstructionException

getBinding

public static <T extends Binding> T getBinding(java.lang.Class<?> clazz,
                                               java.lang.Class<?>... parameters)
                                    throws BindingConstructionException
Get a binding for 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:
ClassBindingFactory

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 for well-known classes where the caller is 100% sure that a binding is construable without exception.

Parameters:
clazz -
Returns:
binding
Throws:
RuntimeBindingConstructionException

getBindingUnchecked

public static <T extends Binding> T getBindingUnchecked(java.lang.Class<?> clazz,
                                                        java.lang.Class<?>... parameters)
                                             throws RuntimeBindingConstructionException
Get a binding for 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
RuntimeBindingConstructionException
See Also:
ClassBindingFactory

addBinding

public static void addBinding(Binding binding,
                              java.lang.Class<?> clazz,
                              java.lang.Class<?>... parameters)
Add a simple binding to reflection binding factory.

Parameters:
binding -
clazz -
parameters - parameter classes

addBindingFactory

public static void addBindingFactory(BindingSubFactory factory)
Add binding factory for compositive bindings

Parameters:
factory -

getBeanBindingRequest

public static BindingRequest getBeanBindingRequest(Datatype type)
                                            throws RuntimeBindingConstructionException
Creates a bean class

Parameters:
type -
Returns:
class
Throws:
RuntimeBindingConstructionException

getBeanClass

public static java.lang.Class<?> getBeanClass(Datatype type)
                                       throws BindingConstructionException
Creates a bean class

Parameters:
type -
Returns:
class
Throws:
BindingConstructionException

getBeanBinding

public static Binding getBeanBinding(Datatype type)
                              throws RuntimeBindingConstructionException
Create binding from datatype that instantiates java classes. RecordTypes are Beans, UnionTypes are Classes with @Union annotation, ArrayTypes are [].

Parameters:
type -
Returns:
class
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 conversion is not posible, e.g. converting value 500 from Integer to Byte. Note, there is also a possibility of precision loss, in many conversions e.g. from double to int.

Parameters:
domain - binding of the source instance
range - binding of the result instance
Returns:
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. Exceptions are run-time. Use this if it safe to assume the conversion will be successful.

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
Adapt and clone a value instance to another type. Immutable bindings may return the argument as is, others return a cloned 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. This method throws only runtime exceptions. Use this if it is safe to assume that the conversion will be successful.

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 two data values for order. Returns a negative integer, zero, or a positive integer if, the first argument precedes/lesser than the second, is equal to, or successor/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