Package org.modeshape.graph.connector.base

This package defines a series of classes that can serve as base classes for a connector implementation.


Interface Summary
BaseRepositorySource An extension of the BaseRepositorySource class that provides a cache policy and a repository context.
Node A snapshot of a single node within a map-based repository.
NodeCachingRepositorySource<KeyType,NodeType extends Node>  
NodeCachingWorkspace<KeyType,NodeType extends Node>  
PathWorkspace.ChangeCommand<NodeType extends PathNode> A specific operation that mutates the underlying persistent repository.
Transaction<NodeType extends Node,WorkspaceType extends Workspace> A transaction in which all read and write operations against a repository are performed.
Workspace The MapWorkspace stores state and other information about a workspace in a way that is independent of Transactions.

Class Summary
AbstractNodeCachingRepositorySource<KeyType,NodeType extends Node>  
AbstractRepositorySource Basic implementation of BaseRepositorySource, providing default implementations of the accessors and mutators in that interface.
BaseTransaction<NodeType extends Node,WorkspaceType extends Workspace>  
Connection<NodeType extends Node,WorkspaceType extends Workspace> A connection to a Repository.
MapNode A Node implementation used by the hashed-based connector (see MapWorkspace and MapTransaction), which stores all node state keyed by the node's hash (or identifier).
MapTransaction<NodeType extends MapNode,WorkspaceType extends MapWorkspace<NodeType>> An implementation of Transaction that maintains a cache of nodes by their hash (or UUID).
MapWorkspace<NodeType extends MapNode> The Workspace implementation that represents all nodes as MapNode objects and stores them keyed by their UUID.
PathNode A Node implementation used by the path-based connector (see PathWorkspace and PathTransaction), which stores all node state in a tree of content, where a specific path exists to each node in the tree.
PathTransaction<NodeType extends PathNode,WorkspaceType extends PathWorkspace<NodeType>> An implementation of Transaction that maintains a cache of nodes by their path.
PathWorkspace<NodeType extends PathNode> The Workspace implementation that represents all nodes as PathNode objects and stores them in an internal data structure that allows for nodes to be accessed via a Path.
Processor<NodeType extends Node,WorkspaceType extends Workspace> The default implementation of the RequestProcessor for map repositories.
Repository<NodeType extends Node,WorkspaceType extends Workspace> A representation of a repository as a set of named workspaces.
StandardMapWorkspace<NodeType extends MapNode> The Workspace implementation that represents all nodes as MapNode objects and stores them within a Map keyed by their UUID.

Package org.modeshape.graph.connector.base Description

This package defines a series of classes that can serve as base classes for a connector implementation. The sources that are accessed by connectors organize their data in various ways, so the connector API doesn't require any particular implementation. However, since many connectors can be implemented in similar ways and often do similar kinds of operations, this package provides a number of concrete and abstract classes that reduce the amount of work required to implement a fully-capable connector. Of course, these classes won't work in all situations not may it be as optimized as when writing a completely dedicated connector. But when you can use them, they make writing a connector much easier and faster.


The main class for a connector is a concrete implementation of the RepositorySource interface. This subclass defines JavaBean properties that can be easily configured, and then implements the RepositorySource.getConnection() method to return a RepositoryConnection.

Providing an abstract class for RepositorySource actually wouldn't provide much benefit, so you still have to provide your own implementation. Along with defining the various JavaBean properties, your class should do two things each time the getConnection() method is called:

  1. Instantiate and manage a single transient Repository instance (or reuse if already created); and
  2. Create and return a new Connection instance.
However, this framework does define a BaseRepositorySource interface that extend the RepositorySource interface with a few additional methods needed by this framework.

The Connection class is a concrete implementation of RepositoryConnection that executes the requests by creating a Transaction, using a fully-implemented Processor to process all of the requests, and either commits or rolls back the transaction if all requests succeeded or if any failed, respectively.

You can use the concrete Connection class as is, but you will have to write a concrete Transaction implementation since that is where all of the source-specific logic goes. This package does offer a couple of different specializations of Transaction that may fit how your connector stores its data (see below).

The Repository class manages a set of named Workspace objects, but it is responsible for startTransaction(...) creating the Transaction objects. Thus, Repository is an abstract class, so you must create a concrete subclass an instantiate it in your BaseRepositorySource's getConnection() method.

To summarize, this connector foundation defines the following concepts:

Of course, before you do this, see if your source fits one of the patterns described below. If it does, the procedure is a little different and will be less work.

Sources with hierarchical content

Many sources store their content in a hierarchical manner. For example, consider file systems, version control systems, directories, repositories, and registries all organize their content using a folder-like construct that relies upon the path from the entry point down to the desired location. This framework provides a number of base classes that can be used to easily create a path-oriented connector.

Sources with content keyed by UUID

Other sources store their content based not upon a path but rather using a unique key for each bit of information. For example, consider data grids and maps all store content using a unique key. This framework provides several base classes that can be used to easily create a UUID-based connector.

MapNode is a serializable representation of a node's properties and child references. Each MapNode has a UUID, and thus all child references are managed as UUIDs. MapNode instances are stored in a MapWorkspace that can be thought of as a wrapper around a Map-like data structure. The MapTransaction is an abstract class that implements all the Map-oriented operations, creates MapWorkspace objects when needed, and tracks changes to the nodes that are either committed or rolled back by the Connection.

A StandardMapWorkspace is provided to simplify working with a real underlying Map where all nodes are stored. If your source does not have a real Map interface, simply subclass MapWorkspace to define how to get and put nodes into the source's representation of the workspace.

To summarize, if your source actually provides a Map implementation, you will:

See Also:

Copyright © 2008-2011 JBoss, a division of Red Hat. All Rights Reserved.