org.simantics.databoard
Class Databoard

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

public class Databoard
extends java.lang.Object


Field Summary
 AdapterFactory adapterFactory
          Adapter Factory
 Binding BEAN
           
 BindingRepository bindingRepository
          Repository of class Bindings
 ClassBindingFactory classBindingFactory
          Reflection based Binding Factory, create binding to class
 TypeBindingFactory defaultBindingFactory
          Default Bindings Factory
 java.util.Map<Datatype,Binding> defaultBindingRepository
          Repository of default bindings
 TypeBindingFactory mutableBindingFactory
          Mutable Bindings Factory
 java.util.Map<Datatype,Binding> mutableBindingRepository
          Repository of mutable bindings
 VariantBinding OBJECT
           
 SerializerFactory serializationFactory
          Serializer Factory
 java.util.Map<Binding,Serializer> serializerRepository
          Repository of serializers
 VariantBinding STR_VARIANT
           
 TypeClassFactory typeClassFactory
          Class Factory
 VariantBinding VARIANT
           
 
Constructor Summary
Databoard()
           
 
Method Summary
 java.lang.Object adapt(java.lang.Object value, Binding domain, Binding range)
          Adapt a value of one type to another.
 java.lang.Object adaptUnchecked(java.lang.Object value, Binding domain, Binding range)
          Adapt a value of one type to another.
 void addBinding(Binding binding, java.lang.Class<?> clazz, java.lang.Class<?>... parameters)
          Add a simple binding to reflection binding factory.
 void addBindingFactory(BindingSubFactory factory)
          Add binding factory for compositive bindings
 java.lang.Object clone(java.lang.Object value, Binding domain, Binding range)
          Adapt and clone a value instance to another type.
 java.lang.Object cloneUnchecked(java.lang.Object value, Binding domain, Binding range)
          Clone a value of one binding to another.
 int compare(Binding b1, java.lang.Object o1, Binding b2, java.lang.Object o2)
          Compares two data values for order.
 java.util.Comparator<java.lang.Object> createComparator(Binding b1, Binding b2)
           
 boolean equals(Binding b1, java.lang.Object o1, Binding b2, java.lang.Object o2)
          Compare two data values for equality.
 Adapter getAdapter(Binding domain, Binding range)
          Create an adapter that adapts two bindings of the same data type.
 Adapter getAdapterUnchecked(Binding domain, Binding range)
          Create an adapter that adapts between two bindings of the same data type.
 Binding getBeanBinding(Datatype type)
          Create binding from datatype that instantiates java classes.
 BindingRequest getBeanBindingRequest(Datatype type)
          Creates a bean class
 java.lang.Class<?> getBeanClass(Datatype type)
          Creates a bean class
<T extends Binding>
T
getBinding(BindingRequest request)
           
<T extends Binding>
T
getBinding(java.lang.Class<?> clazz)
          Get a binding to a Java Class.
<T extends Binding>
T
getBinding(java.lang.Class<?> clazz, java.lang.Class<?>... parameters)
          Get a binding for a Java Class.
<T extends Binding>
T
getBinding(Datatype type)
          Get or create a binding based on default java classes, such as Integer.class, or byte[].class.
<T extends Binding>
T
getBindingUnchecked(java.lang.Class<?> clazz)
          Read binding and type from a class.
<T extends Binding>
T
getBindingUnchecked(java.lang.Class<?> clazz, java.lang.Class<?>... parameters)
          Get a binding for a Java Class.
<T extends Binding>
T
getMutableBinding(Datatype type)
          Get or create a binding that is completely mutable java class.
 Serializer getSerializer(Binding binding)
          Get serializer that follows Databoard serialization spec.
 Serializer getSerializer(java.lang.Class<?> clazz)
          Get serializer that follows Databoard serialization spec.
 Serializer getSerializerUnchecked(Binding binding)
          Get serializer that follows Databoard serialization spec.
 Serializer getSerializerUnchecked(java.lang.Class<?> clazz)
          Get serializer that follows Databoard serialization spec.
 Adapter getTypeAdapter(Binding domain, Binding range)
          Create a type adapter that adapts instances from one Datatype to another.
 Adapter getTypeAdapterUnchecked(Binding domain, Binding range)
          Create a type adapter that adapts instances from one DataType to another.
 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 final java.util.Map<Datatype,Binding> mutableBindingRepository
Repository of mutable bindings


defaultBindingRepository

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


bindingRepository

public final BindingRepository bindingRepository
Repository of class Bindings


serializerRepository

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


mutableBindingFactory

public final TypeBindingFactory mutableBindingFactory
Mutable Bindings Factory


defaultBindingFactory

public final TypeBindingFactory defaultBindingFactory
Default Bindings Factory


classBindingFactory

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


serializationFactory

public final SerializerFactory serializationFactory
Serializer Factory


adapterFactory

public final AdapterFactory adapterFactory
Adapter Factory


typeClassFactory

public final TypeClassFactory typeClassFactory
Class Factory


VARIANT

public final VariantBinding VARIANT

OBJECT

public final VariantBinding OBJECT

STR_VARIANT

public final VariantBinding STR_VARIANT

BEAN

public final Binding BEAN
Constructor Detail

Databoard

public Databoard()
Method Detail

getMutableBinding

public <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 <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 <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).

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

getBinding

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

getBinding

public <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 = getBinding(Map.class, String.class, Integer.class); Map map = (Map) binding.createDefault(); Example 2: Binding d = getBinding(List.class, Integer.class); List list = (List) d.createRandom(5); Example 3: Binding d = getBinding(List.class, List.class, Integer.class); List> list = (List>) d.createRandom(5);

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

getBindingUnchecked

public <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 <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 = getBinding(Map.class, String.class, Integer.class); Map map = (Map) binding.createDefault(); Example 2: Binding d = getBinding(List.class, Integer.class); List list = (List) d.createRandom(5); Example 3: Binding d = 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 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 void addBindingFactory(BindingSubFactory factory)
Add binding factory for compositive bindings

Parameters:
factory -

getBeanBindingRequest

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

Parameters:
type -
Returns:
class
Throws:
RuntimeBindingConstructionException

getBeanClass

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

Parameters:
type -
Returns:
class
Throws:
BindingConstructionException

getBeanBinding

public 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 Serializer getSerializer(Binding binding)
                         throws SerializerConstructionException
Get serializer that follows Databoard serialization spec.

Parameters:
binding -
Returns:
serializer
Throws:
SerializerConstructionException

getSerializerUnchecked

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

Parameters:
binding -
Returns:
serializer
Throws:
RuntimeSerializerConstructionException

getSerializer

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

Parameters:
clazz -
Returns:
serializer
Throws:
SerializerConstructionException

getSerializerUnchecked

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

Parameters:
clazz -
Returns:
serializer serializer
Throws:
RuntimeSerializerConstructionException

getAdapter

public 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 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 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 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 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 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 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 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 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 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 java.util.Comparator<java.lang.Object> createComparator(Binding b1,
                                                               Binding b2)

toString

public 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