org.simantics.databoard.binding
Class Binding

java.lang.Object
  extended by org.simantics.databoard.binding.Binding
All Implemented Interfaces:
java.util.Comparator<java.lang.Object>
Direct Known Subclasses:
ArrayBinding, BooleanBinding, MapBinding, NumberBinding, OptionalBinding, RecordBinding, StringBinding, UnionBinding, VariantBinding

public abstract class Binding
extends java.lang.Object
implements java.util.Comparator<java.lang.Object>

This class represents connection between abstract datatype and java class. A binding allows an access to an Object in scope of a datatype.

For example, IntegerBinding gives unified access to any integer class (Integer, int, MutableInteger, UnsignedInteger). There is same unification for primitive types and constructed types (record, map, array, union, variant).

You can get a hold of binding several ways: 1) Use one of the default bindings e.g. Bindings.BYTE_ARRAY 2) Create one using Datatype Bindings.getMutableBinding(Datatype) 3) Create one using Reflectiong Bindings.getBinding(Class) 4) Instantiate binding your self. e.g. new TreeMapBinding( Bindings.STRING, Bindings.STRING ); 5) Sub-class one of the abstract binding classes

Author:
Toni Kalajainen , Hannu Niemisto
See Also:
BooleanBinding, ByteBinding, IntegerBinding, LongBinding, FloatBinding, DoubleBinding, StringBinding, RecordBinding, ArrayBinding, MapBinding, OptionalBinding, UnionBinding, See examples/BindingExample.java, Facade class Bindings provices extra functionality.

Nested Class Summary
static interface Binding.Visitor<T>
           
static interface Binding.Visitor1
           
 
Constructor Summary
Binding()
           
 
Method Summary
abstract
<T> T
accept(Binding.Visitor<T> v)
           
abstract  void accept(Binding.Visitor1 v, java.lang.Object obj)
           
 void assertInstaceIsValid(java.lang.Object obj)
          Assert the obj is valid data type
abstract  void assertInstaceIsValid(java.lang.Object obj, java.util.Set<java.lang.Object> validInstances)
          Assert the obj is valid data type
 java.lang.Object clone(java.lang.Object o)
          Make a complete copy of a the java object.
 java.lang.Object cloneUnchecked(java.lang.Object o)
           
 int compare(java.lang.Object o1, java.lang.Object o2)
          Compares its two data values for order.
 java.lang.Object createDefault()
          Create a value with valid default values.
 java.lang.Object createDefaultUnchecked()
           
 java.lang.Object createRandom(int seed)
          Create random valid value.
 java.lang.Object createRandomUnchecked(int seed)
           
abstract  int deepCompare(java.lang.Object o1, java.lang.Object o2, java.util.Set<IdentityPair<java.lang.Object,java.lang.Object>> compareHistory)
           
abstract  int deepHashValue(java.lang.Object value, java.util.IdentityHashMap<java.lang.Object,java.lang.Object> hashedObjects)
          Calculate hash value
 boolean equals(java.lang.Object o1, java.lang.Object o2)
          Compare two Java Objects of this binding for equality.
abstract  Binding getComponentBinding(ChildReference path)
          Get component binding
abstract  Binding getComponentBinding(int index)
          Get component binding
abstract  int getComponentCount()
          Get component binding count
 int hashValue(java.lang.Object value)
          Calculate Hash code for a Data Value.
 boolean isImmutable()
          Return true if the value is immutable.
abstract  boolean isInstance(java.lang.Object obj)
           
 java.lang.Object parseValue(java.io.Reader stream, DataValueRepository repository)
          Parse data value from a text to a value instance.
 java.lang.Object parseValue(java.lang.String text, DataValueRepository repository)
          Parse data value from a text to a value instance.
 java.lang.Object parseValueDefinition(java.lang.String text)
          Parse data value from a text to a value instance.
 void printValue(java.lang.Object value, java.lang.Appendable out, DataValueRepository valueRepository, boolean singleLine)
          Print a value to an appendable using data value notation.
 java.lang.String printValueDefinition(java.lang.Object value, boolean singleLine)
          Print a value as a data value repository.
abstract  void readFrom(Binding srcBinding, java.lang.Object src, java.lang.Object dst)
          Read values from another object.
 Serializer serializer()
          Deprecated. Instead use Bindings.getSerializerUnchecked(Binding) or SerializerScheme.getSerializerUnchecked(Binding)
 java.lang.String toString(java.lang.Object value)
           
 Datatype type()
          Get Value Type
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface java.util.Comparator
equals
 

Constructor Detail

Binding

public Binding()
Method Detail

type

public Datatype type()
Get Value Type

Returns:
value type

accept

public abstract void accept(Binding.Visitor1 v,
                            java.lang.Object obj)

accept

public abstract <T> T accept(Binding.Visitor<T> v)

serializer

@Deprecated
public Serializer serializer()
                      throws RuntimeSerializerConstructionException
Deprecated. Instead use Bindings.getSerializerUnchecked(Binding) or SerializerScheme.getSerializerUnchecked(Binding)

Get or create default serializer. Binary Serialization format

Returns:
serializer for this binding
Throws:
RuntimeSerializerConstructionException

isInstance

public abstract boolean isInstance(java.lang.Object obj)

isImmutable

public boolean isImmutable()
Return true if the value is immutable. This question excludes the immutability of the component types.

Returns:
true value if immutable

readFrom

public abstract void readFrom(Binding srcBinding,
                              java.lang.Object src,
                              java.lang.Object dst)
                       throws BindingException
Read values from another object.

Parameters:
srcBinding -
src -
dst - valid object of this binding
Throws:
BindingException

assertInstaceIsValid

public void assertInstaceIsValid(java.lang.Object obj)
                          throws BindingException
Assert the obj is valid data type

Parameters:
obj - the instance
Throws:
BindingException - on invalid instance

assertInstaceIsValid

public abstract void assertInstaceIsValid(java.lang.Object obj,
                                          java.util.Set<java.lang.Object> validInstances)
                                   throws BindingException
Assert the obj is valid data type

Parameters:
obj - the instance
validInstances - optional set of already validated instances
Throws:
BindingException - on invalid instance

parseValue

public java.lang.Object parseValue(java.io.Reader stream,
                                   DataValueRepository repository)
                            throws DataTypeSyntaxError,
                                   BindingException
Parse data value from a text to a value instance. Datavalue notation

Parameters:
stream -
Returns:
the value
Throws:
BindingException
ParseException
DataTypeSyntaxError

parseValue

public java.lang.Object parseValue(java.lang.String text,
                                   DataValueRepository repository)
                            throws DataTypeSyntaxError,
                                   BindingException
Parse data value from a text to a value instance. Datavalue Notation

Parameters:
text -
Returns:
the value
Throws:
BindingException
ParseException
DataTypeSyntaxError

parseValueDefinition

public java.lang.Object parseValueDefinition(java.lang.String text)
                                      throws DataTypeSyntaxError,
                                             BindingException
Parse data value from a text to a value instance. Datavalue Notation

Parameters:
text -
Returns:
the value
Throws:
BindingException
ParseException
DataTypeSyntaxError

printValueDefinition

public java.lang.String printValueDefinition(java.lang.Object value,
                                             boolean singleLine)
                                      throws java.io.IOException,
                                             BindingException
Print a value as a data value repository. Datavalue notation

Parameters:
value -
singleLine -
Returns:
the value in ascii format
Throws:
java.io.IOException
BindingException

printValue

public void printValue(java.lang.Object value,
                       java.lang.Appendable out,
                       DataValueRepository valueRepository,
                       boolean singleLine)
                throws java.io.IOException,
                       BindingException
Print a value to an appendable using data value notation. Datavalue Notation

Parameters:
value -
out -
singleLine -
Throws:
java.io.IOException
BindingException

hashValue

public int hashValue(java.lang.Object value)
              throws BindingException
Calculate Hash code for a Data Value. Type Hash Function ------------------------------------------------ Boolean true=1231, false=1237 Integer value Long lower 32-bits ^ higher 32-bits Float IEEE 754 floating-point "single format" bit layout as is. Double lower 32-bits ^ higher 32-bits of IEEE 754 floating-point "double format" bit layout. Optional no value = 0, else hash(value) Array int result = 1; for (int element : array) result = 31 * result + hash(element); Record int result = 3; for (field : record) result = 31 * result + hash(field) (See *); Variant hash(type) + hash(value) Union tag + hash(value) Map int result = 0; for (entry : map) result += hash(key) ^ hash(value); Byte value *) In case of recursion, the function (hash or compareTo) will not enter same value twice. 0 is returned in such a case.

Parameters:
value -
Returns:
hash value
Throws:
BindingException

deepHashValue

public abstract int deepHashValue(java.lang.Object value,
                                  java.util.IdentityHashMap<java.lang.Object,java.lang.Object> hashedObjects)
                           throws BindingException
Calculate hash value

Parameters:
value -
hashedObjects - collection of already hashed object or optionally null
Returns:
hash value
Throws:
BindingException

compare

public int compare(java.lang.Object o1,
                   java.lang.Object o2)
            throws RuntimeBindingException
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.

The implementor must also ensure that the relation is transitive: ((compare(x, y)>0) && (compare(y, z)>0)) implies compare(x, z)>0.

Finally, the implementor must ensure that compare(x, y)==0 implies that sgn(compare(x, z))==sgn(compare(y, z)) for all z.

The comparison function is defined at http://dev.simantics.org/index.php/Org.simantics.databoard_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.

Specified by:
compare in interface java.util.Comparator<java.lang.Object>
Parameters:
o1 - the first object to be compared.
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
RuntimeBindingException

equals

public boolean equals(java.lang.Object o1,
                      java.lang.Object o2)
               throws RuntimeBindingException
Compare two Java Objects of this binding for equality.

Parameters:
o1 -
o2 -
Returns:
true if equal
Throws:
RuntimeBindingException

clone

public java.lang.Object clone(java.lang.Object o)
                       throws AdaptException
Make a complete copy of a the java object. Bindings that handle immutable values may return the same instance, others will guarantee a complete copy.

Note, this is a generic implementation, override for better performance.

Parameters:
o - to be cloned
Returns:
a complete copy
Throws:
AdapterConstructionException
AdaptException

cloneUnchecked

public java.lang.Object cloneUnchecked(java.lang.Object o)
                                throws RuntimeAdaptException
Throws:
RuntimeAdaptException

deepCompare

public abstract int deepCompare(java.lang.Object o1,
                                java.lang.Object o2,
                                java.util.Set<IdentityPair<java.lang.Object,java.lang.Object>> compareHistory)
                         throws BindingException
Throws:
BindingException

createDefault

public java.lang.Object createDefault()
                               throws BindingException
Create a value with valid default values. Boolean false Byte, Integer, Long 0 Float, Double 0.0 String "" (may not follow pattern) Optional *novalue* Union tag 0 Record each field with default value Array min range number of elements Map no entries Variant Optional with no value

Returns:
default value
Throws:
BindingException

createDefaultUnchecked

public java.lang.Object createDefaultUnchecked()
                                        throws RuntimeBindingException
Throws:
RuntimeBindingException

createRandom

public java.lang.Object createRandom(int seed)
                              throws BindingException
Create random valid value.

Parameters:
seed - random seed
Returns:
random value
Throws:
BindingException

createRandomUnchecked

public java.lang.Object createRandomUnchecked(int seed)
                                       throws RuntimeBindingException
Throws:
RuntimeBindingException

toString

public java.lang.String toString(java.lang.Object value)
                          throws BindingException
Throws:
BindingException

getComponentCount

public abstract int getComponentCount()
Get component binding count

Returns:
component count

getComponentBinding

public abstract Binding getComponentBinding(int index)
Get component binding

Parameters:
index -
Returns:
binding

getComponentBinding

public abstract Binding getComponentBinding(ChildReference path)
Get component binding

Parameters:
path - child path or null to return this.
Returns:
binding
Throws:
java.lang.IllegalArgumentException - if path cannot be applied to this binding