com.neeve.rog
Interface IRogGraphCollection

public interface IRogGraphCollection

Represents a collection (forest) of object graphs.

Threading:

A graph collection not safe for concurrent access by multiple threads.

An ROG graph collection manages a set of ROG root nodes. Each node uniquely identifies an ROG instance and is identified by a graph id. The graph collection supports the addition and removal of graph nodes (root as well as non-root nodes) and retrieval of root nodes.

Node Addition
When an ROG node is added to a graph collection, the collection first determines whether the node is a root ROG node or not. If it is, the node is added to the root node set managed by the collection. Otherwise, the node's parent is retrieved from the ODS store that contains the added node the added node linked to its parent. It should be noted that objects linked into their graph using the add facility offered by a graph collection first needs to be added to an ODS store before being supplied to the collection for addition.

Node Removal
When an ROG node is removed from a graph collection, the collection first determines whether the node is a root ROG node or not. If it is, the node is removed from the root node set managed by the collection. Otherwise, the node is unlinked from its parent.

Node Retrieval
Only root nodes can be retrieved from a collection.

Users typically link/unlink ROG nodes to/from their graphs using the graph collection addition/removal mechanism only on replicated (backup) endpoints. On primary endpoints, the recommended use is to add/remove root nodes to/from their graph collection but to directly link child objects into their graph via setter/getter methods offered by the child's parent nodes (which, in turn, use the facilities offered by container nodes to manage their children)

Method Summary

void	add(IRogNode node) Add an ROG node into a graph collection.
IRogRootNode	get(int grid) Get a root ROG node from the graph collection.
IStoreBinding	getInitialStore() Get the store a graph collection was created with.
IStoreBinding	getStore() Get a graph collection's store.
void	remove(IRogNode node) Remove an ROG node from a graph collection.

Method Detail

getInitialStore

IStoreBinding getInitialStore()

Get the store a graph collection was created with.

A graph collection can be created attached to an initial store. Graphs added to the collection are automatically added to the collection's store. If the initial store is null, then the collection inherits the store of the first graph added to it. If the initial store is non-null, then each graph added to the collection must either not be associated with a store (in which case it is put in the collection's store) or associated with the same store as the collection.

getStore

IStoreBinding getStore()

Get a graph collection's store.

Prior to the first graph added to a collection, this method will return the same value as getInitialStore(). Subsequent to the addition of the first graph, the value returned by this method will be the store resolved for the graph - the initial store if non-null or else the first added graph's store.

Note: For instances of a graph collection without an initial store but layered on stores such as StoreBinding, the store initialized dynamically from the first added graph would be the store associated with the graph root which is not the StoreBinding but rather the core binding that underlies it.

add

void add(IRogNode node)

Add an ROG node into a graph collection.

Parameters:

node - The node to add.

Throws:

IllegalArgumentException - Thrown in the following conditions:
1. If the node being added is null.
2. If the node being added is not a root node and its parent is not a container node i.e. not of type IRogContainerNode

IllegalStateException - Thrown in the following conditions:
1. If the node being added is a root node and is already present in a collection
2. If the node being added is a root node and a root node with the same graph id is already in the collection (validated only in checked mode of operation).
3. If the node being added is a root node and is already present in a store different from the store bound to the collection.
4. If the node being added is not a root node and is not present in an ODS store.
5. If the node being added is not a root node and the store to which it belongs is different from the store bound to the collection.
6. If the node being added is not a root node and its parent is not in the same store as the node being added.

This method adds a new ROG node to a graph collection. The method first checks if the supplied node is a root node. If so, the node is added to store bound to the collection the root node set managed by the graph collection. Otherwise, the method finds the node's parent from the ODS store bound to the node (the node needs to be in an ODS store before this method is invoked) and adds the node to the parent node as a child node.

Note: This method can only be used in scenarios where a collection is bound to a non-null store and the node being added is already in the same store bound to the collection at the time it is added to the collection.

get

IRogRootNode get(int grid)

Get a root ROG node from the graph collection.

Parameters:

grid - The id of the graph of which the desired node is the root.

remove

void remove(IRogNode node)

Remove an ROG node from a graph collection.

Parameters:

node - The node to remove.

Throws:

IllegalArgumentException - Thrown if the specified node is null.

This method removed an ROG node from a graph collection. The method first checks if the supplied node is a root node. If so, the node is removed from the root node set managed by the graph collection. Otherwise, the method gets the node's parent unlinked from the node.