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>

Binding is an object that makes modifications and conversions between values of a Datatype and instances of a Java Class possible. If the Datatype is structural, so is the corresponding binding, and the structure is the same. There are 13 datatypes, and there is one binding type for each corresponding datatype. See examples/BindingExample.java

Author:
Hannu Niemisto, Toni Kalajainen
See Also:
Bindings

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.
 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)
           
static void main(java.lang.String[] args)
           
 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.
 Serializer serializer()
          Deprecated. Instead use Bindings.getSerializerUnchecked(Binding) or SerializationScheme#getSerializerUnchecked(Binding)
 Serializer serializer(SerializationFormat format)
          Create a serializer using a custom serialization format.
 Serializer serializerUnchecked(SerializationFormat format)
          Create a serializer using a custom serialization format.
 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

public Serializer serializer()
                      throws RuntimeSerializerConstructionException
Deprecated. Instead use Bindings.getSerializerUnchecked(Binding) or SerializationScheme#getSerializerUnchecked(Binding)

Create a binary serializer. Binary Serialization format

Returns:
serializer for this binding
Throws:
RuntimeSerializerConstructionException

serializer

public Serializer serializer(SerializationFormat format)
                      throws SerializerConstructionException
Create a serializer using a custom serialization format.

Parameters:
format - serializer format
Returns:
serializer for this binding
Throws:
SerializerConstructionException

serializerUnchecked

public Serializer serializerUnchecked(SerializationFormat format)
Create a serializer using a custom serialization format.

Parameters:
format - serializer format
Returns:
serializer for this binding
Throws:
SerializerConstructionException

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

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 https://www.simantics.org/wiki/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

main

public static void main(java.lang.String[] args)
                 throws BindingException
Throws:
BindingException