- * - * The structure is presentable with Databoard type system. The type can be - * anything but a recursive structure.
- * - * The listening model allows placing of listener objects to accessors. - * Each listener is associated with a InterestSet. It describes a sub-tree of - * nodes to listen and aspects to monitor. Accessors emit Events on modifications - * of structure and value. There is a reference in each event, and it is relative - * to the accessor where the listener was placed. For instance, a listener, that is - * interested in whole tree, is placed on a root accessor. A modification at a - * leaf-node spawns an event with a reference path from the root to the leaf. - * If the listener was placed directly on the leaf, there wouldn't be a path - * in the evenr object.
- * - * Multi-thread-usage is implementation dependent, read the documentation.
- * - * Construction and destruction model is also implementation dependent. - * A rule of thumb in life management of objects is that, the party that - * constructs an object must destroy it. Both construction and destruction of - * the container are also outside the scope of the Accessor interface.
- * - * However, as general implementation contract, the data container is disposed - * as whole, individual nodes are not. While the container is alive, individual - * nodes may be disposed using garbage collection mechanisms. Reference queue - * mechanism is one implementatio strategy. More common strategy is usage of - * weak references from parent to child.
- * - * @see Accessors - * @see JavaObject Accessor to Java Object container - * @see BinaryObject Accessor to a container in File or Memory - * @see ArrayAccessor - * @see BooleanAccessor - * @see ByteAccessor - * @see DoubleAccessor - * @see FloatAccessor - * @see IntegerAccessor - * @see LongAccessor - * @see MapAccessor - * @see OptionalAccessor - * @see RecordAccessor - * @see StringAccessor - * @see UnionAccessor - * @see VariantAccessor - * @author Toni Kalajainen (toni.kalajainen@iki.fi) - */ -public interface Accessor { - - /** - * Get a snapshot of the object as a single data value.
- * Accessor makes type adaption to users binding if possible.
- * - * @param binding - * @return the value - * @throws AccessorException - */ - Object getValue(Binding binding) throws AccessorException; - - /** - * Read a copy of the accessor's object into the obj instance.
- * Accessor makes type adaption to users binding if possible.
- * - * @param binding - * @param obj object to read the value to - * @throws AccessorException - */ - void getValue(Binding binding, Object obj) throws AccessorException; - - /** - * Read value in path reference into an obj instance.
- *
- * @param path component reference path or null to return _this_
- * @param binding
- * @param obj
- * @return true if value existed, false if not
- * @throws AccessorException
- */
- boolean getValue(ChildReference path, Binding binding, Object obj) throws AccessorException;
-
- /**
- * Read value in path reference into an obj instance.
- *
- * @param path component reference path or null to return _this_ accessor
- * @param binding
- * @param obj
- * @return the object or null if value doesn't exist
- * @throws AccessorException
- */
- Object getValue(ChildReference path, Binding binding) throws AccessorException;
-
- /**
- * Set a complete new value to the data container.
- * Accessor makes type adaption to users binding if possible.
- * - * If the new value removes old map entries, array entries, optional value, or - * changes union or variant value type, it will disengage any existing - * sub-accessors and send {@link InvalidatedEvent}.
- * - * Writing the current value again may not emit an event. This is implementation - * specific.
- * - * Write is durable, once a the method returns successfully the value has been - * stored in the implmentation.
- *
- * @param binding
- * @param newValue
- * @throws BindingException binding error
- * @throws UnsupportedOperationException cannot set a new value
- */
- void setValue(Binding binding, Object newValue) throws AccessorException;
-
- /**
- * Set value to path reference.
- *
- * @param path component reference path or null to return _this_
- * @param binding
- * @param obj
- * @return true if value existed in the accessor, false if not
- * @throws AccessorException
- */
- boolean setValue(ChildReference path, Binding binding, Object obj) throws AccessorException;
-
- /**
- * 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.
- *
- * @param path component reference path or
- *
- * 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 {@link ChangeSet} is an implementation that collects events.
- *
- * Executor argument determines the thread where the onEvents method is
- * handled. null argument denotes current thread.
- *
- * @param listener
- * @param interestSet
- * @param pathPrefix path to the accessor or
+ *
+ * The structure is presentable with Databoard type system. The type can be
+ * anything but a recursive structure.
+ *
+ * The listening model allows placing of listener objects to accessors.
+ * Each listener is associated with a InterestSet. It describes a sub-tree of
+ * nodes to listen and aspects to monitor. Accessors emit Events on modifications
+ * of structure and value. There is a reference in each event, and it is relative
+ * to the accessor where the listener was placed. For instance, a listener, that is
+ * interested in whole tree, is placed on a root accessor. A modification at a
+ * leaf-node spawns an event with a reference path from the root to the leaf.
+ * If the listener was placed directly on the leaf, there wouldn't be a path
+ * in the evenr object.
+ *
+ * Multi-thread-usage is implementation dependent, read the documentation.
+ *
+ * Construction and destruction model is also implementation dependent.
+ * A rule of thumb in life management of objects is that, the party that
+ * constructs an object must destroy it. Both construction and destruction of
+ * the container are also outside the scope of the Accessor interface.
+ *
+ * However, as general implementation contract, the data container is disposed
+ * as whole, individual nodes are not. While the container is alive, individual
+ * nodes may be disposed using garbage collection mechanisms. Reference queue
+ * mechanism is one implementatio strategy. More common strategy is usage of
+ * weak references from parent to child.
+ *
+ * @see Accessors
+ * @see JavaObject Accessor to Java Object container
+ * @see BinaryObject Accessor to a container in File or Memory
+ * @see ArrayAccessor
+ * @see BooleanAccessor
+ * @see ByteAccessor
+ * @see DoubleAccessor
+ * @see FloatAccessor
+ * @see IntegerAccessor
+ * @see LongAccessor
+ * @see MapAccessor
+ * @see OptionalAccessor
+ * @see RecordAccessor
+ * @see StringAccessor
+ * @see UnionAccessor
+ * @see VariantAccessor
+ * @author Toni Kalajainen (toni.kalajainen@iki.fi)
+ */
+public interface Accessor {
+
+ /**
+ * Get a snapshot of the object as a single data value.
+ * Accessor makes type adaption to users binding if possible.
+ *
+ * @param binding
+ * @return the value
+ * @throws AccessorException
+ */
+ Object getValue(Binding binding) throws AccessorException;
+
+ /**
+ * Read a copy of the accessor's object into the obj instance.
+ * Accessor makes type adaption to users binding if possible.
+ *
+ * @param binding
+ * @param obj object to read the value to
+ * @throws AccessorException
+ */
+ void getValue(Binding binding, Object obj) throws AccessorException;
+
+ /**
+ * Read value in path reference into an obj instance.
+ *
+ * @param path component reference path or
+ *
+ * @param path component reference path or
+ *
+ * If the new value removes old map entries, array entries, optional value, or
+ * changes union or variant value type, it will disengage any existing
+ * sub-accessors and send {@link InvalidatedEvent}.
+ *
+ * Writing the current value again may not emit an event. This is implementation
+ * specific.
+ *
+ * Write is durable, once a the method returns successfully the value has been
+ * stored in the implmentation.
+ *
+ * @param binding
+ * @param newValue
+ * @throws BindingException binding error
+ * @throws UnsupportedOperationException cannot set a new value
+ */
+ void setValue(Binding binding, Object newValue) throws AccessorException;
+
+ /**
+ * Set value to path reference.
+ *
+ * @param path component reference path or
+ *
+ * InvalidatedEvent is thrown from the accessor if it is unlinked from the
+ * parent hierarchy.
+ *
+ * @param path component reference path or
+ *
+ * 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 {@link ChangeSet} is an implementation that collects events.
+ *
+ * Executor argument determines the thread where the onEvents method is
+ * handled. null argument denotes current thread.
+ *
+ * @param listener
+ * @param interestSet
+ * @param pathPrefix path to the accessor or null to return _this_ accessor
- * @return accessor
- * @throws AccessorConstructionException
- */
- null
- * @throws AccessorException failed to apply change set
- */
- void apply(Listnull. This is used in the events the accessor produces
- * @param executor
- * @see ChangeSet collects events
- */
- void addListener(Listener listener, InterestSet interestSet, ChildReference pathPrefix, Executor executor) throws AccessorException;
-
- /**
- * Remove a listener. If the listener is added multiple times, the last
- * one added is removed.
- *
- * @param listener
- * @throws AccessorException
- */
- void removeListener(Listener listener) throws AccessorException;
-
- /**
- * Accessor listener.
- *
- * @author Toni Kalajainen null to return _this_
+ * @param binding
+ * @param obj
+ * @return true if value existed, false if not
+ * @throws AccessorException
+ */
+ boolean getValue(ChildReference path, Binding binding, Object obj) throws AccessorException;
+
+ /**
+ * Read value in path reference into an obj instance. null to return _this_ accessor
+ * @param binding
+ * @param obj
+ * @return the object or null if value doesn't exist
+ * @throws AccessorException
+ */
+ Object getValue(ChildReference path, Binding binding) throws AccessorException;
+
+ /**
+ * Set a complete new value to the data container.
+ * Accessor makes type adaption to users binding if possible. null to return _this_
+ * @param binding
+ * @param obj
+ * @return true if value existed in the accessor, false if not
+ * @throws AccessorException
+ */
+ boolean setValue(ChildReference path, Binding binding, Object obj) throws AccessorException;
+
+ /**
+ * 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.null to return _this_ accessor
+ * @return accessor
+ * @throws AccessorConstructionException
+ */
+ null
+ * @throws AccessorException failed to apply change set
+ */
+ void apply(Listnull. This is used in the events the accessor produces
+ * @param executor
+ * @see ChangeSet collects events
+ */
+ void addListener(Listener listener, InterestSet interestSet, ChildReference pathPrefix, Executor executor) throws AccessorException;
+
+ /**
+ * Remove a listener. If the listener is added multiple times, the last
+ * one added is removed.
+ *
+ * @param listener
+ * @throws AccessorException
+ */
+ void removeListener(Listener listener) throws AccessorException;
+
+ /**
+ * Accessor listener.
+ *
+ * @author Toni Kalajainen