org.simantics.databoard.accessor.binary
Class BinaryObject

java.lang.Object
  extended by org.simantics.databoard.accessor.binary.BinaryObject
All Implemented Interfaces:
Accessor, CloseableAccessor, FileAccessor, ParametrisedAccessor
Direct Known Subclasses:
BinaryArray, BinaryBoolean, BinaryByte, BinaryDouble, BinaryFloat, BinaryInteger, BinaryLong, BinaryMap, BinaryOptional, BinaryRecord, BinaryString, BinaryUnion, BinaryVariant

public abstract class BinaryObject
extends java.lang.Object
implements Accessor, FileAccessor, CloseableAccessor, ParametrisedAccessor

BinaryObject is an accessor to a binary object, usually a random access file. BinaryObject cannot handle files of recursive types.

The file can be opened once. It may not be modified by any other instance other than accessor while accessors are beign used. You must not create more than one instance of BinaryObjects for a file.

Author:
Toni Kalajainen
See Also:
BinaryArray, BinaryBoolean, BinaryByte, BinaryDouble, BinaryFloat, BinaryInteger, BinaryLong, BinaryMap, BinaryOptional, BinaryRecord, BinaryString, BinaryUnion, BinaryVariant

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.simantics.databoard.accessor.Accessor
Accessor.Listener
 
Method Summary
 void addListener(Accessor.Listener listener, InterestSet interestSet, ChildReference path)
          Place a listener to an accessor node.
 void apply(java.util.List<Event> cs, java.util.LinkedList<Event> rollback)
          Apply a change set in a single transaction operation.
 void close()
          Close the random access file beneath
static BinaryObject createAccessor(RandomAccessBinary binary, Datatype type, AccessorParams params)
           
 java.io.File file()
          Get file if the binary object is based on binary file.
 void flush()
          Flush the internal write buffer to the disc.
 RandomAccessBinary getBinary()
           
 EventEmitter getEmitter()
           
 AccessorParams getParams()
          Get accessor parameters
 java.util.concurrent.locks.Lock getReadLock()
          Get lock if available.
 RandomAccessBinary getSource()
           
 java.lang.Object getValue(Binding binding)
          Get a snapshot of the object model as a single data value.
 void getValue(Binding binding, java.lang.Object obj)
          Read a copy of the accessor's object into an instance.
 java.util.concurrent.locks.Lock getWriteLock()
          Get lock if available.
 void removeListener(Accessor.Listener listener)
          Remove a listener.
 void setValue(Binding binding, java.lang.Object newValue)
          Write a new value and flush the buffer.
abstract  void setValueNoflush(Binding binding, java.lang.Object newValue)
          Write a new value and don't flush the buffer
 java.lang.String toString()
           
 Datatype type()
          Get structural represtentation of the accessor presented in databoard's type system.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.simantics.databoard.accessor.Accessor
getComponent
 

Method Detail

type

public Datatype type()
Description copied from interface: Accessor
Get structural represtentation of the accessor presented in databoard's type system.

Specified by:
type in interface Accessor
Returns:
type description

flush

public void flush()
           throws AccessorException
Description copied from interface: FileAccessor
Flush the internal write buffer to the disc. This is needed if setXXNoFlush() methods are used.

Note, all the write methods of Accessor and its sub-interfaces guarantee Durability. They flush the value immediately and do not require separate FileAccessor.flush().

Specified by:
flush in interface FileAccessor
Throws:
AccessorException

getSource

public RandomAccessBinary getSource()

close

public void close()
           throws AccessorException
Close the random access file beneath

Specified by:
close in interface CloseableAccessor
Specified by:
close in interface FileAccessor
Throws:
AccessorException

file

public java.io.File file()
Get file if the binary object is based on binary file.

Specified by:
file in interface FileAccessor
Returns:
file or null

getBinary

public RandomAccessBinary getBinary()

getParams

public AccessorParams getParams()
Description copied from interface: ParametrisedAccessor
Get accessor parameters

Specified by:
getParams in interface ParametrisedAccessor
Returns:
accessor parameters

addListener

public void addListener(Accessor.Listener listener,
                        InterestSet interestSet,
                        ChildReference path)
                 throws AccessorException
Description copied from interface: Accessor
Place a listener to an accessor node. The listener will be notified for changes in the node/node tree, depending on interest set.

When events are emited and in which thread processed is implementation specific. It is also implementation specific, whether the object can be mutated in the listener or whether it has to be done afterwards.

In many implementations there is a pluggable event handling strategy EventEmitter. The default behaviour is to emit events as they are spawned in the current thread.

There is a reference in each event instance that describes the path from the accessor where listener was placed to the node to which the event applies to.

Listener is attached to the object that holds the value at the time at the of the adding. For example, If a listener is attached to an array of element at index 3, and a new value is inserted at position 2, the listener still monitors the same container, which is now at index 4. The references of incoming the events are modified to have the new index.

Also, if a new value is assigned to the parent of an object that is listened, the listener keeps on monitoring the new value at the same reference. This doesn't apply when a new value is set to a union of different tag, to a variant with a new type, or value is removed from Optional type. In these two cases the listener is invalidated.

See ChangeSet is an implementation that collects events.

Specified by:
addListener in interface Accessor
path - path to the accessor or null. This is used in the events the accessor produces
Throws:
AccessorException
See Also:
collects events

removeListener

public void removeListener(Accessor.Listener listener)
                    throws AccessorException
Description copied from interface: Accessor
Remove a listener. If the listener is added multiple times, the last one added is removed.

Specified by:
removeListener in interface Accessor
Throws:
AccessorException

setValue

public void setValue(Binding binding,
                     java.lang.Object newValue)
              throws AccessorException
Write a new value and flush the buffer.

Specified by:
setValue in interface Accessor
Parameters:
binding -
newValue -
Throws:
AccessorException

setValueNoflush

public abstract void setValueNoflush(Binding binding,
                                     java.lang.Object newValue)
                              throws AccessorException
Write a new value and don't flush the buffer

Specified by:
setValueNoflush in interface FileAccessor
Parameters:
binding -
newValue -
Throws:
AccessorException

getValue

public java.lang.Object getValue(Binding binding)
                          throws AccessorException
Description copied from interface: Accessor
Get a snapshot of the object model as a single data value.

Specified by:
getValue in interface Accessor
Returns:
the value
Throws:
AccessorException

getValue

public void getValue(Binding binding,
                     java.lang.Object obj)
              throws AccessorException
Description copied from interface: Accessor
Read a copy of the accessor's object into an instance.

Specified by:
getValue in interface Accessor
obj - object to read the value to
Throws:
AccessorException

apply

public void apply(java.util.List<Event> cs,
                  java.util.LinkedList<Event> rollback)
           throws AccessorException
Description copied from interface: Accessor
Apply a change set in a single transaction operation. If rollback log is supplied, it is filled with reverse events. If the operation fails, rollback log can be applied to cancel changes.

Specified by:
apply in interface Accessor
rollback - log to be filled with rollback events or null
Throws:
AccessorException - failed to apply change set

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

createAccessor

public static BinaryObject createAccessor(RandomAccessBinary binary,
                                          Datatype type,
                                          AccessorParams params)
                                   throws AccessorConstructionException
Throws:
AccessorConstructionException

getEmitter

public EventEmitter getEmitter()

getReadLock

public java.util.concurrent.locks.Lock getReadLock()
Get lock if available.

Returns:
lock or null

getWriteLock

public java.util.concurrent.locks.Lock getWriteLock()
Get lock if available.

Returns:
lock or null