|
||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
See:
Description
Interface Summary | |
---|---|
PropertyChangeRequest | Marker interface for ChangeRequest classes that operate only upon properties. |
Class Summary | |
---|---|
AccessQueryRequest | A Request to issue an access query a graph, where an access query is a low-level atomic query that is part of a large,
planned query. |
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. |
CollectGarbageRequest | Request that garbage collection be performed. |
CompositeRequest | A request that wraps multiple other requests, allowing multiple requests to be treated as a single request. |
CompositeRequestChannel | A channel for Request objects that can be submitted to a consumer (typically a RequestProcessor or
RepositoryConnection ) while allowing the channel owner to continue adding more Request objects into the channel. |
CompositeRequestChannel.LastRequest | A psuedo Request that is used by the CompositeRequestChannel to insert into a request queue so that the queue's
iterator knows when there are no more requests to process. |
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. |
FullTextSearchRequest | A Request to perform a full-text search on a graph. |
FunctionRequest | |
GetWorkspacesRequest | A request to obtain the information about the workspaces that are available. |
LockBranchRequest | Instruction to lock an existing node or branch. |
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. |
SearchRequest | A Request to search or query a graph. |
SetPropertyRequest | Instruction to set a particular property on the node at the specified location. |
UnlockBranchRequest | Instruction to unlock an existing node or branch. |
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. |
LockBranchRequest.LockScope | |
RequestType | Enumeration of supported request types. |
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. |
MultipleRequestFailuresException | A RequestException that wraps multiple failed Request objects. |
RequestException | Specifies that the request was invalid and could not be completed. |
UnsupportedRequestException | Specifies that the request was a type that is not supported. |
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 ModeShape 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.)
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.
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.
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 ModeShape 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.
There are really two very broad categories of Request
s: 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:
ReadNodeRequest
- A request to read the specified node and return all of that node's properties and the
location of every child node.ReadAllChildrenRequest
- A request to read and return all of the children of the specified node.
Each child node is represented by a Location
object. This request is useful for
determining the structure of the graph without having to load all of the properties of each node.ReadAllPropertiesRequest
- A request to read and return all of the properties of the specified node.
This request is useful when all of the properties for a node are to be returned, but without any children
information (usually because the children will be read later or were already read).ReadBranchRequest
- A request to read a branch of the graph, returning the node (with its properties
and children) at the specified location as well as nodes (with their properties and children) below the specified node,
up to an optional maximum depth. This request is useful for efficiently obtaining the nodes in a subgraph when
the structure is known ahead of time. This request can sometimes be significantly more efficient that walking
the subgraph and submitting individual ReadNodeRequest
s for each node in the subgraph.ReadPropertyRequest
- A request to read and return a single named property on a specified node.ReadBlockOfChildrenRequest
- A request to read the children of the specified node, returning only
the locations for a subset of the children. The subset of children is defined by the index of the first child
to be returned and the number of children to be returned. This is often useful when the repository may have large numbers
of children and it is unlikely that client applications will need all of them. ReadNextBlockOfChildrenRequest
- A request to read the children of the specified node, returning
only the locations for a subset of the children. Unlike ReadBlockOfChildrenRequest
, this request
specifies the Location of the child that appears immediately before the first child to be returned. This
request is useful in concurrent applications when one client is reading the children while another client
may be adding or removing children (thereby changing the indexes). Since this request includes the Location of the
last child previously read, the request is unaffected by changing indexes.CreateNodeRequest
- A request to create a new node under an existing parent node. This request
may optionally include properties for the new node.CopyBranchRequest
- A request to copy an entire branch located under a specified node, and place
the copy of that branch under another (existing) node.MoveBranchRequest
- A request to move the specified node and all nodes below it into a new location
specified by the Location of the new parent node.RenameNodeRequest
- A request to rename an existing node. This may adjust the indexes of sibling nodes
with the same names (as same-name-sibling nodes are identified with SNS indexes).UpdatePropertiesRequest
- A request to update one or more properties on a node. Any property
with no values will be removed, while properties with one or more values will be set (replace any existing property
with the same name, if they exist). RemovePropertyRequest
- A request to remove one property from a node. No error is reported
if the node does not contain a property that is to be removed.SetPropertyRequest
- A request to set one property on a node. No error is reported
if the node does not already have the property, since the property is just created.DeleteBranchRequest
- A request to delete a node and all nodes located below it.CompositeRequest
- A request that acts as a container for multiple other requests (of various kinds),
allowing you to batch together multiple for processing. Use the one of the CompositeRequest.with(...)
methods to create a CompositeRequest from a series of other requests.
|
||||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |