Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## Package org.modeshape.graph.connector.base

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

See:
Description

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 `Transaction`s.

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.

### Foundation

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:

- Define a `Node` implementation class that represents a graph node.
- Define a `Workspace` implementation class that represents each named workspace in your source.
- Define a concrete `BaseRepositorySource` subclass that manages a single `Repository` instance and create `Connection` objects.
- Define a `Repository` subclass that manages the `Workspace` objects and create `Transaction` objects for use by the `Connection`.
- Define a `Transaction` class that implements all of the source-specific logic for interacting with the underlying source of data.

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:

- Use directly or create a subclass of `MapNode`.
- Define a `MapWorkspace<YourMapNode>` class that represents each named workspace in your source, or simply reuse `StandardMapWorkspace<YourMapNode>` if your source uses a `Map`.
- Define a `MapTransaction<YourMapNode,YourMapWorkspace>` concrete subclass that implements all of the source-specific logic for interacting with the underlying source of data.
- Define a `Repository<YourMapNode,YourMapWorkspace>` subclass that manages the `MapWorkspace<YourMapNode>` objects and create `MapTransaction<YourMapNode,YourMapWorkspace>` objects for use by the `Connection`.
- Define a concrete `BaseRepositorySource` subclass that manages a single `Repository<YourMapNode,YourMapWorkspace>` instance and create `Connection` objects.

See Also:
  `InMemoryRepositorySource`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

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