org.simantics.databoard.accessor.binary
Class BinaryMap

java.lang.Object
  extended by org.simantics.databoard.accessor.binary.BinaryObject
      extended by org.simantics.databoard.accessor.binary.BinaryMap
All Implemented Interfaces:
Accessor, CloseableAccessor, FileAccessor, FileMapAccessor, MapAccessor, ParametrisedAccessor

public class BinaryMap
extends BinaryObject
implements MapAccessor, FileMapAccessor

BinaryMap is accessor to a map structure in a file or byte memory.

(Fixed sized entries) If the size of an entry is constant, then the implementation uses binary search for random access operations O(log(n)).

(Variable sized entries) If the size is variable, for example the key or value is string, then the implementation does sequential search for all operations, which is very slow O(n). To improve performance, an index is built in memory as the file is read. To conserve memory, the index is held with SoftReference. So, the performance remains good if lots of operations are done within a short time period.

Author:
Toni Kalajainen

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.simantics.databoard.accessor.Accessor
Accessor.Listener
 
Constructor Summary
BinaryMap(BinaryObject parent, Blob blob, Datatype type, AccessorParams params)
           
 
Method Summary
 void addListener(Accessor.Listener listener, InterestSet interestSet, ChildReference path, java.util.concurrent.Executor executor)
          Place a listener to an accessor node.
 void clear()
          Clear all entries.
 void clearNoflush()
           
 boolean containsKey(Binding keyBinding, java.lang.Object key)
          Returns true if map has a value for specified key
 boolean containsValue(Binding valueBinding, java.lang.Object value)
          Returns true if map has a value for one or multiple keys
 int count(Binding keyBinding, java.lang.Object from, boolean fromInclusive, java.lang.Object end, boolean endInclusive)
          Count the number of entries between two keyes
 java.lang.Object get(Binding keyBinding, java.lang.Object key, Binding valueBinding)
          Get the value that is specified for a key
 void getAll(Binding keyBinding, Binding valueBinding, java.util.Map<java.lang.Object,java.lang.Object> to)
          Get all entries, write to a Java Collection
 void getAll(Binding keyBinding, Binding valueBinding, java.lang.Object[] keys, java.lang.Object[] values)
          Get all entries in order, write to 2 arrays.
 java.lang.Object getCeilingKey(Binding keyBinding, java.lang.Object key)
           
<T extends Accessor>
T
getComponent(ChildReference reference)
          Open an accessor to a child.
 int getEntries(Binding keyBinding, java.lang.Object from, boolean fromInclusive, java.lang.Object end, boolean endInclusive, ArrayBinding keyArrayBinding, java.lang.Object keysArray, ArrayBinding valueArrayBinding, java.lang.Object valueArray, int limit)
          Read a range of entries
 java.lang.Object getFirstKey(Binding keyBinding)
           
 java.lang.Object getFloorKey(Binding keyBinding, java.lang.Object key)
           
 java.lang.Object getHigherKey(Binding keyBinding, java.lang.Object key)
           
 java.lang.Object[] getKeys(Binding keyBinding)
          Get all keys in order
 java.lang.Object getLastKey(Binding keyBinding)
           
 java.lang.Object getLowerKey(Binding keyBinding, java.lang.Object key)
           
<T extends Accessor>
T
getValueAccessor(Binding keyBinding, java.lang.Object key)
          Get an accessor to a value.
 java.lang.Object[] getValues(Binding valueBinding)
          Get all values
 void put(Binding keyBinding, java.lang.Object key, Binding valueBinding, java.lang.Object value)
          Put an entry to the map.
 void putAll(Binding keyBinding, Binding valueBinding, java.util.Map<java.lang.Object,java.lang.Object> from)
          Put entries from a map.
 void putAll(Binding keyBinding, Binding valueBinding, java.lang.Object[] keys, java.lang.Object[] values)
          Put entries from a map.
 void putAllNoflush(Binding keyBinding, Binding valueBinding, java.util.Map<java.lang.Object,java.lang.Object> from)
           
 void putAllNoflush(Binding kb, Binding vb, java.lang.Object[] nks, java.lang.Object[] nvs)
           
 void putNoflush(Binding kb, java.lang.Object key, Binding vb, java.lang.Object value)
          Put an entry to the map.
 void remove(Binding keyBinding, java.lang.Object key)
          Remove an entry.
 void removeListener(Accessor.Listener listener)
          Remove a listener.
 void removeNoflush(Binding keyBinding, java.lang.Object key)
           
 void setAllNoflush(Binding kb, Binding vb, java.lang.Object[] nks, java.lang.Object[] nvs)
           
 void setValueNoflush(Binding binding, java.lang.Object mapValue)
          Write a new value and don't flush the buffer
 int size()
          Get the number of elements in the map
 MapType type()
          Get structural represtentation of the accessor presented in databoard's type system.
 
Methods inherited from class org.simantics.databoard.accessor.binary.BinaryObject
apply, close, createAccessor, file, flush, getBinary, getParams, getReadLock, getSource, getValue, getValue, getWriteLock, isOpen, reset, setValue, toString
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.simantics.databoard.accessor.MapAccessor
setValue
 
Methods inherited from interface org.simantics.databoard.accessor.file.FileAccessor
close, file, flush, reset
 
Methods inherited from interface org.simantics.databoard.accessor.Accessor
apply, getValue, getValue
 

Constructor Detail

BinaryMap

public BinaryMap(BinaryObject parent,
                 Blob blob,
                 Datatype type,
                 AccessorParams params)
Method Detail

type

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

Specified by:
type in interface Accessor
Specified by:
type in interface MapAccessor
Overrides:
type in class BinaryObject
Returns:
type description

clear

public void clear()
           throws AccessorException
Description copied from interface: MapAccessor
Clear all entries. If there is an accessor to a removed container, it becomes invalid.

Specified by:
clear in interface MapAccessor
Throws:
AccessorException

size

public int size()
         throws AccessorException
Description copied from interface: MapAccessor
Get the number of elements in the map

Specified by:
size in interface MapAccessor
Returns:
size
Throws:
AccessorException

containsKey

public boolean containsKey(Binding keyBinding,
                           java.lang.Object key)
                    throws AccessorException
Description copied from interface: MapAccessor
Returns true if map has a value for specified key

Specified by:
containsKey in interface MapAccessor
Returns:
true if entry exists
Throws:
AccessorException

containsValue

public boolean containsValue(Binding valueBinding,
                             java.lang.Object value)
                      throws AccessorException
Description copied from interface: MapAccessor
Returns true if map has a value for one or multiple keys

Specified by:
containsValue in interface MapAccessor
Returns:
true if value exists
Throws:
AccessorException

get

public java.lang.Object get(Binding keyBinding,
                            java.lang.Object key,
                            Binding valueBinding)
                     throws AccessorException
Description copied from interface: MapAccessor
Get the value that is specified for a key

Specified by:
get in interface MapAccessor
Returns:
the value or null
Throws:
AccessorException

getAll

public void getAll(Binding keyBinding,
                   Binding valueBinding,
                   java.util.Map<java.lang.Object,java.lang.Object> to)
            throws AccessorException
Description copied from interface: MapAccessor
Get all entries, write to a Java Collection

Specified by:
getAll in interface MapAccessor
Throws:
AccessorException

getAll

public void getAll(Binding keyBinding,
                   Binding valueBinding,
                   java.lang.Object[] keys,
                   java.lang.Object[] values)
            throws AccessorException
Description copied from interface: MapAccessor
Get all entries in order, write to 2 arrays.

Specified by:
getAll in interface MapAccessor
Throws:
AccessorException

count

public int count(Binding keyBinding,
                 java.lang.Object from,
                 boolean fromInclusive,
                 java.lang.Object end,
                 boolean endInclusive)
          throws AccessorException
Description copied from interface: MapAccessor
Count the number of entries between two keyes

Specified by:
count in interface MapAccessor
Returns:
number of entries in range
Throws:
AccessorException

getEntries

public int getEntries(Binding keyBinding,
                      java.lang.Object from,
                      boolean fromInclusive,
                      java.lang.Object end,
                      boolean endInclusive,
                      ArrayBinding keyArrayBinding,
                      java.lang.Object keysArray,
                      ArrayBinding valueArrayBinding,
                      java.lang.Object valueArray,
                      int limit)
               throws AccessorException
Description copied from interface: MapAccessor
Read a range of entries

Specified by:
getEntries in interface MapAccessor
limit - maximum number of entries to read, -1 for no limit
Returns:
the number of entries read
Throws:
AccessorException

getCeilingKey

public java.lang.Object getCeilingKey(Binding keyBinding,
                                      java.lang.Object key)
                               throws AccessorException
Specified by:
getCeilingKey in interface MapAccessor
Throws:
AccessorException

getFirstKey

public java.lang.Object getFirstKey(Binding keyBinding)
                             throws AccessorException
Specified by:
getFirstKey in interface MapAccessor
Throws:
AccessorException

getFloorKey

public java.lang.Object getFloorKey(Binding keyBinding,
                                    java.lang.Object key)
                             throws AccessorException
Specified by:
getFloorKey in interface MapAccessor
Throws:
AccessorException

getHigherKey

public java.lang.Object getHigherKey(Binding keyBinding,
                                     java.lang.Object key)
                              throws AccessorException
Specified by:
getHigherKey in interface MapAccessor
Throws:
AccessorException

getKeys

public java.lang.Object[] getKeys(Binding keyBinding)
                           throws AccessorException
Description copied from interface: MapAccessor
Get all keys in order

Specified by:
getKeys in interface MapAccessor
Returns:
an array or keys
Throws:
AccessorException

getLastKey

public java.lang.Object getLastKey(Binding keyBinding)
                            throws AccessorException
Specified by:
getLastKey in interface MapAccessor
Throws:
AccessorException

getLowerKey

public java.lang.Object getLowerKey(Binding keyBinding,
                                    java.lang.Object key)
                             throws AccessorException
Specified by:
getLowerKey in interface MapAccessor
Throws:
AccessorException

getComponent

public <T extends Accessor> T getComponent(ChildReference reference)
                                throws AccessorConstructionException
Description copied from interface: Accessor
Open an accessor to a child. If one already exists, the existing is returned, otherwise a new is created. Child accessors are often remembered with weak reference.

InvalidatedEvent is thrown from the accessor if it is unlinked from the parent hierarchy.

Specified by:
getComponent in interface Accessor
Parameters:
reference - component reference path or null to return _this_ accessor
Returns:
accessor
Throws:
AccessorConstructionException

getValueAccessor

public <T extends Accessor> T getValueAccessor(Binding keyBinding,
                                               java.lang.Object key)
                                    throws AccessorConstructionException
Description copied from interface: MapAccessor
Get an accessor to a value. It becomes invalid if the entry is removed or overwritten with a new value.

Specified by:
getValueAccessor in interface MapAccessor
Returns:
value accessor
Throws:
AccessorConstructionException

getValues

public java.lang.Object[] getValues(Binding valueBinding)
                             throws AccessorException
Description copied from interface: MapAccessor
Get all values

Specified by:
getValues in interface MapAccessor
Returns:
an array of values
Throws:
AccessorException

setValueNoflush

public void setValueNoflush(Binding binding,
                            java.lang.Object mapValue)
                     throws AccessorException
Description copied from class: BinaryObject
Write a new value and don't flush the buffer

Specified by:
setValueNoflush in interface FileAccessor
Specified by:
setValueNoflush in interface FileMapAccessor
Specified by:
setValueNoflush in class BinaryObject
Throws:
AccessorException

clearNoflush

public void clearNoflush()
                  throws AccessorException
Specified by:
clearNoflush in interface FileMapAccessor
Throws:
AccessorException

putAllNoflush

public void putAllNoflush(Binding keyBinding,
                          Binding valueBinding,
                          java.util.Map<java.lang.Object,java.lang.Object> from)
                   throws AccessorException
Specified by:
putAllNoflush in interface FileMapAccessor
Throws:
AccessorException

putAllNoflush

public void putAllNoflush(Binding kb,
                          Binding vb,
                          java.lang.Object[] nks,
                          java.lang.Object[] nvs)
                   throws AccessorException
Specified by:
putAllNoflush in interface FileMapAccessor
Throws:
AccessorException

setAllNoflush

public void setAllNoflush(Binding kb,
                          Binding vb,
                          java.lang.Object[] nks,
                          java.lang.Object[] nvs)
                   throws AccessorException
Throws:
AccessorException

putNoflush

public void putNoflush(Binding kb,
                       java.lang.Object key,
                       Binding vb,
                       java.lang.Object value)
                throws AccessorException
Description copied from interface: FileMapAccessor
Put an entry to the map. If previous entry exists for the key, it is removed.

Specified by:
putNoflush in interface FileMapAccessor
Throws:
AccessorException

removeNoflush

public void removeNoflush(Binding keyBinding,
                          java.lang.Object key)
                   throws AccessorException
Specified by:
removeNoflush in interface FileMapAccessor
Throws:
AccessorException

addListener

public void addListener(Accessor.Listener listener,
                        InterestSet interestSet,
                        ChildReference path,
                        java.util.concurrent.Executor executor)
                 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. Executor argument determines the thread where the onEvents method is handled. null argument denotes current thread.

Specified by:
addListener in interface Accessor
Overrides:
addListener in class BinaryObject
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
Overrides:
removeListener in class BinaryObject
Throws:
AccessorException

put

public void put(Binding keyBinding,
                java.lang.Object key,
                Binding valueBinding,
                java.lang.Object value)
         throws AccessorException
Description copied from interface: MapAccessor
Put an entry to the map. If previous entry exists for the key, it is removed.

Specified by:
put in interface MapAccessor
Throws:
AccessorException

putAll

public void putAll(Binding keyBinding,
                   Binding valueBinding,
                   java.util.Map<java.lang.Object,java.lang.Object> from)
            throws AccessorException
Description copied from interface: MapAccessor
Put entries from a map. Replaces any possible existing entry.

Specified by:
putAll in interface MapAccessor
Throws:
AccessorException

putAll

public void putAll(Binding keyBinding,
                   Binding valueBinding,
                   java.lang.Object[] keys,
                   java.lang.Object[] values)
            throws AccessorException
Description copied from interface: MapAccessor
Put entries from a map. Replaces any possible existing entry.

Specified by:
putAll in interface MapAccessor
Throws:
AccessorException

remove

public void remove(Binding keyBinding,
                   java.lang.Object key)
            throws AccessorException
Description copied from interface: MapAccessor
Remove an entry. If there is an accessor, it becomes invalid.

Specified by:
remove in interface MapAccessor
Throws:
AccessorException