Package org.jboss.dna.graph.request

Sometimes its useful to work with a graph using objects that represent individual commands on the graph.

See:
          Description


Class Summary
BatchRequestBuilder A component that can be used to build up a list of requests.
CacheableRequest A request that contains results that may be cached.
ChangeRequest A Request to make changes in a graph.
CloneBranchRequest Instruction that a branch be cloned from one workspace into another.
CloneWorkspaceRequest Request that an existing workspace be cloned into a target workspace with the supplied name.
CompositeRequest A request that wraps multiple other requests, allowing multiple requests to be treated as a single request.
CopyBranchRequest Instruction that a branch be copied from one location into another.
CreateNodeRequest Instruction to create the node under the specified location.
CreateWorkspaceRequest Request that a new workspace be created with the supplied name.
DeleteBranchRequest Instruction that a branch be deleted.
DeleteChildrenRequest Instruction that all nodes below a supplied node be deleted.
DestroyWorkspaceRequest Request that an existing workspace with the supplied name be destroyed.
GetWorkspacesRequest A request to obtain the information about the workspaces that are available.
MoveBranchRequest Instruction that a branch be moved from one location into another.
ReadAllChildrenRequest Instruction to read all of the children of a node at a specific location.
ReadAllPropertiesRequest Instruction to read the properties and the number of children of the node at the specifed location.
ReadBlockOfChildrenRequest Instruction to read a block of the children of a node, where the block is dictated by the starting index and the maximum number of children to include in the block.
ReadBranchRequest Instruction to read the properties and children of the nodes in the branch at the supplied location.
ReadNextBlockOfChildrenRequest Instruction to read a block of the children of a node, where the block is dictated by the location of the child preceding the block and the maximum number of children to include in the block.
ReadNodeRequest Instruction to read the properties and children of the node at the specifed location.
ReadPropertyRequest Instruction to read a single property on the node at the specified location.
RemovePropertyRequest Instruction to remove the property with the supplied name from the node at the given location.
RenameNodeRequest Instruction to rename an existing node (but keep it under the same parent).
Request The abstract base class for all classes representing requests to be executed against a RepositoryConnection.
RequestBuilder A component that can be used to build requests while allowing different strategies for how requests are handled.
SetPropertyRequest Instruction to set a particular property on the node at the specified location.
UpdatePropertiesRequest Instruction to update the properties on the node at the specified location.
UpdateValuesRequest Instruction to update the values for a certain property on the node at the specified location.
VerifyNodeExistsRequest Instruction to verify the existance of a node at the specified location.
VerifyWorkspaceRequest Verify that a workspace exists with the supplied name.
 

Enum Summary
CloneWorkspaceRequest.CloneConflictBehavior The options for the behavior when a request specifies the name of the workspace to clone, but the cloned workspace does not exist.
CreateWorkspaceRequest.CreateConflictBehavior The options for the behavior when a request specifies a workspace name that already is used by an existing workspace.
 

Exception Summary
InvalidRequestException Specifies that the request was invalid and could not be completed.
InvalidWorkspaceException Specifies that the request was invalid and could not be completed.
RequestException Specifies that the request was invalid and could not be completed.
UnsupportedRequestException Specifies that the request was a type that is not supported.
 

Package org.jboss.dna.graph.request Description

Sometimes its useful to work with a graph using objects that represent individual commands on the graph. For example, "read node A" or "create a node named C under node /A/B" or "create a copy of the subgraph at /E/F/G and place it under /E/H/I". The command pattern has a number of benefits. Since commands represent atomic activities, they map well to events and can be easily serialized (making them very useful for connectors). They provide an easy way to inherit or override functionality. New kinds of commands can be added with minimal (sometimes no) impact. And existing commands can be changed to include new fields, making it possible to evolve a command while minimizing the changes.

This package defines standard commands, called "requests", that correspond to different kinds of actions against a JBoss DNA graph. Each kind of request is represented by a single concrete class, and all request classes extend from the Request abstract class. Because a lot of inheritance among commands can cause interference and inheritance cross-talk, inheritance other than from Request is avoided as much possible. (One exception to this is CacheableRequest, which extends Request and serves as the base class for the "read" requests that return results.)

Processing Requests

Request objects are sent to a RequestProcessor, which is responsible for performing the request. Repository connectors usually implement their own RequestProcessor, which processes each submitted request by performing the requested work.

Processor generally do not throw exceptions when processing requests (other than errors that signal problems with the processor itself, such as connectivity problems, that signals the interruption of not only this request but subsequent requests, too). Instead, each request has an error field that can be used to store the exception that was encountered while processing the request. This makes it possible to submit multiple requests at once, and have any errors directly associated with the request.

What's in a Request?

In general, a single request contains two kinds of information: the information that makes up the request (called the "input"), and the information that is the result of the request (called the "result"). The input information contains everything a processor needs to know to successfully perform the request. For example, if the properties of a node are to be read, then the input information must include the identifier or location of the node. If a node is to be moved, then the input information must include the original location of the node as well as the new location. Oh, the request's input information is immutable, ensuring that this part of the request doesn't change as it is passed around the system.

A processor then fulfills the request by performing the requested work, and setting on the request any requested "results". For example, if the properties of a node are to be read, then the results include the set of Property objects. If the children are to be read, then the results consist of the list of Location object for each child.

Locations

All requests operate on some portion of the graph, so it's imperative that there be an easy but flexible way to identify the location of that area, whether it's a node, subgraph, child reference, or node reference. Like other parts of the JBoss DNA Graph API, requests use Location (or multiple Location objects) as request inputs, and one Location object for each "reference" to a node that's in the output.

A Location can be specified as a Path and/or as a set of identification properties. Usually, Locations are created using just the path, since that's how nodes are identified most of the time. However, identification properties usually consist of information that uniquely (and quickly) identifies a node, so including identification properties in a Location may allow the processor to easily or more efficiently find the node given by the location.

Fortunately, requests often return Location objects that are fully-defined, meaning they have a Path and identification properties. For example, the children of a node will be returned as a list of (fully-defined) Location objects. In fact, all requests have as part of their results an "actual" Location for each Location in the input, so even when you don't have a fully-defined Location as an input, the request (after processing) should contain a fully-defined Location for the input.

Because of this, and because working with a graph usually consists of making one request, using the results of that request to create additional requests, and so on, you'll find that it's very easy to include fully-defined Location objects in your requests. Well, except for the first request.

Kinds of Requests

There are really two very broad categories of Requests: requests that don't modify content and those that do. The requests that don't modify content are generally "read" requests that are requests to return information about some part of the graph, and these requests should really have not side-effects on the graph. Since these requests contain results that are essentially snapshots in time of a portion of the graph content, these request types extend CacheableRequest and contain fields for referencing a CachePolicy and a time that the results were loaded.

Requests that do modify graph content are used to create, update, move and delete content in the graph. These kinds of requests often have little or no results (the changes will be made to the graph unless an exception is set on the request during processing), and as such the requests do not have any fields related to caching.

The supported requests currently include:



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