Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

javax.jcr
Interface Session

public interface Session

The Session object provides read and (in level 2) write access to the content of a particular workspace in the repository.

The Session object is returned by Repository.login(). It encapsulates both the authorization settings of a particular user (as specified by the passed Credentials) and a binding to the workspace specified by the workspaceName passed on login.

Each Session object is associated one-to-one with a Workspace object. The Workspace object represents a "view" of an actual repository workspace entity as seen through the authorization settings of its associated Session.

Field Summary
static java.lang.String ACTION_ADD_NODE
          A constant representing the add_node action string, used to determine if this Session has permission to add a new node.
static java.lang.String ACTION_READ
          A constant representing the read action string, used to determine if this Session has permission to retrieve an item (and read the value, in the case of a property).
static java.lang.String ACTION_REMOVE
          A constant representing the remove action string, used to determine if this Session has permission to remove an item.
static java.lang.String ACTION_SET_PROPERTY
          A constant representing the set_property action string, used to determine if this Session has permission to set (add or modify) a property.
 
Method Summary
 void addLockToken(java.lang.String lt)
          Deprecated. As of JCR 2.0, LockManager.addLockToken(String) should be used instead.
 void checkPermission(java.lang.String absPath, java.lang.String actions)
          Determines whether this Session has permission to perform the specified actions at the specified absPath.
 void exportDocumentView(java.lang.String absPath, org.xml.sax.ContentHandler contentHandler, boolean skipBinary, boolean noRecurse)
          Serializes the node (and if noRecurse is false, the whole subgraph) at absPath into a series of SAX events by calling the methods of the supplied org.xml.sax.ContentHandler.
 void exportDocumentView(java.lang.String absPath, java.io.OutputStream out, boolean skipBinary, boolean noRecurse)
          Serializes the node (and if noRecurse is false, the whole subgraph) at absPath as an XML stream and outputs it to the supplied OutputStream.
 void exportSystemView(java.lang.String absPath, org.xml.sax.ContentHandler contentHandler, boolean skipBinary, boolean noRecurse)
          Serializes the node (and if noRecurse is false, the whole subgraph) at absPath into a series of SAX events by calling the methods of the supplied org.xml.sax.ContentHandler.
 void exportSystemView(java.lang.String absPath, java.io.OutputStream out, boolean skipBinary, boolean noRecurse)
          Serializes the node (and if noRecurse is false, the whole subgraph) at absPath as an XML stream and outputs it to the supplied OutputStream.
 AccessControlManager getAccessControlManager()
          Returns the access control manager for this Session.
 java.lang.Object getAttribute(java.lang.String name)
          Returns the value of the named attribute as an Object, or null if no attribute of the given name exists.
 java.lang.String[] getAttributeNames()
          Returns the names of the attributes set in this session as a result of the Credentials that were used to acquire it.
 org.xml.sax.ContentHandler getImportContentHandler(java.lang.String parentAbsPath, int uuidBehavior)
          Returns an org.xml.sax.ContentHandler which is used to push SAX events to the repository.
 Item getItem(java.lang.String absPath)
          Returns the node at the specified absolute path in the workspace.
 java.lang.String[] getLockTokens()
          Deprecated. As of JCR 2.0, LockManager.getLockTokens() should be used instead.
 java.lang.String getNamespacePrefix(java.lang.String uri)
          Returns the prefix to which the given uri is mapped as currently set in this Session.
 java.lang.String[] getNamespacePrefixes()
          Returns all prefixes currently mapped to URIs in this Session.
 java.lang.String getNamespaceURI(java.lang.String prefix)
          Returns the URI to which the given prefix is mapped as currently set in this Session.
 Node getNode(java.lang.String absPath)
          Returns the node at the specified absolute path in the workspace.
 Node getNodeByIdentifier(java.lang.String id)
          Returns the node specified by the given identifier.
 Node getNodeByUUID(java.lang.String uuid)
          Deprecated. As of JCR 2.0, getNodeByIdentifier(String) should be used instead.
 Property getProperty(java.lang.String absPath)
          Returns the property at the specified absolute path in the workspace.
 Repository getRepository()
          Returns the Repository object through which this session was acquired.
 RetentionManager getRetentionManager()
          Returns the retention and hold manager for this Session.
 Node getRootNode()
          Returns the root node of the workspace, "/".
 java.lang.String getUserID()
          Gets the user ID associated with this Session.
 ValueFactory getValueFactory()
          This method returns a ValueFactory that is used to create Value objects for use when setting repository properties.
 Workspace getWorkspace()
          Returns the Workspace attached to this Session.
 boolean hasCapability(java.lang.String methodName, java.lang.Object target, java.lang.Object[] arguments)
          Checks whether an operation can be performed given as much context as can be determined by the repository, including: Permissions granted to the current user, including access control privileges.
 boolean hasPendingChanges()
          Returns true if this session holds pending (that is, unsaved) changes; otherwise returns false.
 boolean hasPermission(java.lang.String absPath, java.lang.String actions)
          Returns true if this Session has permission to perform the specified actions at the specified absPath and false otherwise.
 Session impersonate(Credentials credentials)
          Returns a new session in accordance with the specified (new) Credentials.
 void importXML(java.lang.String parentAbsPath, java.io.InputStream in, int uuidBehavior)
          Deserializes an XML document and adds the resulting item subgraph as a child of the node at parentAbsPath.
 boolean isLive()
          Returns true if this Session object is usable by the client.
 boolean itemExists(java.lang.String absPath)
          Returns true if an item exists at absPath and this Session has read access to it; otherwise returns false.
 void logout()
          Releases all resources associated with this Session.
 void move(java.lang.String srcAbsPath, java.lang.String destAbsPath)
          Moves the node at srcAbsPath (and its entire subgraph) to the new location at destAbsPath.
 boolean nodeExists(java.lang.String absPath)
          Returns true if a node exists at absPath and this Session has read access to it; otherwise returns false.
 boolean propertyExists(java.lang.String absPath)
          Returns true if a property exists at absPath and this Session has read access to it; otherwise returns false.
 void refresh(boolean keepChanges)
          If keepChanges is false, this method discards all pending changes currently recorded in this Session and returns all items to reflect the current saved state.
 void removeItem(java.lang.String absPath)
          Removes the specified item and its subgraph.
 void removeLockToken(java.lang.String lt)
          Deprecated. As of JCR 2.0, LockManager.removeLockToken(String) should be used instead.
 void save()
          Validates all pending changes currently recorded in this Session.
 void setNamespacePrefix(java.lang.String prefix, java.lang.String uri)
          Within the scope of this Session, this method maps uri to prefix.
 

Field Detail

ACTION_READ

static final java.lang.String ACTION_READ
A constant representing the read action string, used to determine if this Session has permission to retrieve an item (and read the value, in the case of a property).

Since:
JCR 2.0
See Also:
hasPermission(String, String), checkPermission(String, String), Constant Field Values

ACTION_ADD_NODE

static final java.lang.String ACTION_ADD_NODE
A constant representing the add_node action string, used to determine if this Session has permission to add a new node.

Since:
JCR 2.0
See Also:
hasPermission(String, String), checkPermission(String, String), Constant Field Values

ACTION_SET_PROPERTY

static final java.lang.String ACTION_SET_PROPERTY
A constant representing the set_property action string, used to determine if this Session has permission to set (add or modify) a property.

Since:
JCR 2.0
See Also:
hasPermission(String, String), checkPermission(String, String), Constant Field Values

ACTION_REMOVE

static final java.lang.String ACTION_REMOVE
A constant representing the remove action string, used to determine if this Session has permission to remove an item.

Since:
JCR 2.0
See Also:
hasPermission(String, String), checkPermission(String, String), Constant Field Values
Method Detail

getRepository

Repository getRepository()
Returns the Repository object through which this session was acquired.

Returns:
a Repository object.

getUserID

java.lang.String getUserID()
Gets the user ID associated with this Session. How the user ID is set is up to the implementation, it may be a string passed in as part of the credentials or it may be a string acquired in some other way. This method is free to return an "anonymous user ID" or null.

Returns:
the user ID associated with this Session.

getAttributeNames

java.lang.String[] getAttributeNames()
Returns the names of the attributes set in this session as a result of the Credentials that were used to acquire it. Not all Credentials implementations will contain attributes (though, for example, SimpleCredentials does allow for them). This method returns an empty array if the Credentials instance did not provide attributes.

Returns:
A string array containing the names of all attributes passed in the credentials used to acquire this session.

getAttribute

java.lang.Object getAttribute(java.lang.String name)
Returns the value of the named attribute as an Object, or null if no attribute of the given name exists. See getAttributeNames().

Parameters:
name - the name of an attribute passed in the credentials used to acquire this session.
Returns:
the value of the attribute or null if no attribute of the given name exists.

getWorkspace

Workspace getWorkspace()
Returns the Workspace attached to this Session.

Returns:
a Workspace object.

getRootNode

Node getRootNode()
                 throws RepositoryException
Returns the root node of the workspace, "/". This node is the main access point to the content of the workspace.

Returns:
The root node of the workspace: a Node object.
Throws:
RepositoryException - if an error occurs.

impersonate

Session impersonate(Credentials credentials)
                    throws LoginException,
                           RepositoryException
Returns a new session in accordance with the specified (new) Credentials. Allows the current user to "impersonate" another using incomplete or relaxed credentials requirements (perhaps including a user name but no password, for example), assuming that this Session gives them that permission.

The new Session is tied to a new Workspace instance. In other words, Workspace instances are not re-used. However, the Workspace instance returned represents the same actual persistent workspace entity in the repository as is represented by the Workspace object tied to this Session.

Parameters:
credentials - A Credentials object
Returns:
a Session object
Throws:
LoginException - if the current session does not have sufficient access to perform the operation.
RepositoryException - if another error occurs.

getNodeByUUID

Node getNodeByUUID(java.lang.String uuid)
                   throws ItemNotFoundException,
                          RepositoryException
Deprecated. As of JCR 2.0, getNodeByIdentifier(String) should be used instead.

Returns the node specified by the given UUID. Only applies to nodes that expose a UUID, in other words, those of mixin node type mix:referenceable

Parameters:
uuid - A universally unique identifier.
Returns:
A Node.
Throws:
ItemNotFoundException - if the specified UUID is not found.
RepositoryException - if another error occurs.

getNodeByIdentifier

Node getNodeByIdentifier(java.lang.String id)
                         throws ItemNotFoundException,
                                RepositoryException
Returns the node specified by the given identifier. Applies to both referenceable and non-referenceable nodes.

Parameters:
id - An identifier.
Returns:
A Node.
Throws:
ItemNotFoundException - if no node with the specified identifier exists or if this Session does not have read access to the node with the specified identifier.
RepositoryException - if another error occurs.
Since:
JCR 2.0

getItem

Item getItem(java.lang.String absPath)
             throws PathNotFoundException,
                    RepositoryException
Returns the node at the specified absolute path in the workspace. If no such node exists, then it returns the property at the specified path.

This method should only be used if the application does not know whether the item at the indicated path is property or node. In cases where the application has this information, either getNode(java.lang.String) or getProperty(java.lang.String) should be used, as appropriate. In many repository implementations the node and property-specific methods are likely to be more efficient than getItem.

Parameters:
absPath - An absolute path.
Returns:
the specified Item.
Throws:
PathNotFoundException - if no accessible item is found at the specified path.
RepositoryException - if another error occurs.

getNode

Node getNode(java.lang.String absPath)
             throws PathNotFoundException,
                    RepositoryException
Returns the node at the specified absolute path in the workspace.

Parameters:
absPath - An absolute path.
Returns:
the specified Node.
Throws:
PathNotFoundException - If no accessible node is found at the specifed path.
RepositoryException - If another error occurs.
Since:
JCR 2.0

getProperty

Property getProperty(java.lang.String absPath)
                     throws PathNotFoundException,
                            RepositoryException
Returns the property at the specified absolute path in the workspace.

Parameters:
absPath - An absolute path.
Returns:
the specified Property.
Throws:
PathNotFoundException - If no accessible property is found at the specified path.
RepositoryException - if another error occurs.
Since:
JCR 2.0

itemExists

boolean itemExists(java.lang.String absPath)
                   throws RepositoryException
Returns true if an item exists at absPath and this Session has read access to it; otherwise returns false.

Parameters:
absPath - An absolute path.
Returns:
a boolean
Throws:
RepositoryException - if absPath is not a well-formed absolute path.

nodeExists

boolean nodeExists(java.lang.String absPath)
                   throws RepositoryException
Returns true if a node exists at absPath and this Session has read access to it; otherwise returns false.

Parameters:
absPath - An absolute path.
Returns:
a boolean
Throws:
RepositoryException - if absPath is not a well-formed absolute path.
Since:
JCR 2.0

propertyExists

boolean propertyExists(java.lang.String absPath)
                       throws RepositoryException
Returns true if a property exists at absPath and this Session has read access to it; otherwise returns false.

Parameters:
absPath - An absolute path.
Returns:
a boolean
Throws:
RepositoryException - if absPath is not a well-formed absolute path.
Since:
JCR 2.0

move

void move(java.lang.String srcAbsPath,
          java.lang.String destAbsPath)
          throws ItemExistsException,
                 PathNotFoundException,
                 VersionException,
                 ConstraintViolationException,
                 LockException,
                 RepositoryException
Moves the node at srcAbsPath (and its entire subgraph) to the new location at destAbsPath.

This is a session-write method and therefor requires a save to dispatch the change.

The identifiers of referenceable nodes must not be changed by a move. The identifiers of non-referenceable nodes may change.

A ConstraintViolationException is thrown either immediately, on dispatch or on persist, if performing this operation would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

As well, a ConstraintViolationException will be thrown on persist if an attempt is made to separately save either the source or destination node.

Note that this behavior differs from that of Workspace.move(java.lang.String, java.lang.String), which is a workspace-write method and therefore immediately dispatches changes.

The destAbsPath provided must not have an index on its final element. If ordering is supported by the node type of the parent node of the new location, then the newly moved node is appended to the end of the child node list.

This method cannot be used to move an individual property by itself. It moves an entire node and its subgraph.

If no node exists at srcAbsPath or no node exists one level above destAbsPath (in other words, there is no node that will serve as the parent of the moved item) then a PathNotFoundException is thrown either immediately, on dispatch or on persist. Implementations may differ on when this validation is performed.

An ItemExistsException is thrown either immediately, on dispatch or on persist, if a node already exists at destAbsPath and same-name siblings are not allowed. Implementations may differ on when this validation is performed.

Note that if a property already exists at destAbsPath, the operation succeeds, since a node may have a child node and property with the same name.

A VersionException is thrown either immediately, on dispatch or on persist, if the parent node of destAbsPath or the parent node of srcAbsPath] is read-only due to a checked-in node. Implementations may differ on when this validation is performed.

A LockException is thrown either immediately, on dispatch or on persist, if a lock prevents the move. Implementations may differ on when this validation is performed.

Parameters:
srcAbsPath - the root of the subgraph to be moved.
destAbsPath - the location to which the subgraph is to be moved.
Throws:
ItemExistsException - if a node already exists at destAbsPath and same-name siblings are not allowed.
PathNotFoundException - if either srcAbsPath or destAbsPath cannot be found and this implementation performs this validation immediately.
VersionException - if the parent node of destAbsPath or the parent node of srcAbsPath is versionable and checked-in, or or is non-versionable and its nearest versionable ancestor is checked-in and this implementation performs this validation immediately.
ConstraintViolationException - if a node-type or other constraint violation is detected immediately and this implementation performs this validation immediately.
LockException - if the move operation would violate a lock and this implementation performs this validation immediately.
RepositoryException - if the last element of destAbsPath has an index or if another error occurs.

removeItem

void removeItem(java.lang.String absPath)
                throws VersionException,
                       LockException,
                       ConstraintViolationException,
                       AccessDeniedException,
                       RepositoryException
Removes the specified item and its subgraph.

This is a session-write method and therefore requires a save in order to dispatch the change.

If a node with same-name siblings is removed, this decrements by one the indices of all the siblings with indices greater than that of the removed node. In other words, a removal compacts the array of same-name siblings and causes the minimal re-numbering required to maintain the original order but leave no gaps in the numbering.

A ReferentialIntegrityException will be thrown on dispatch if the specified item or an item in its subgraph is currently the target of a REFERENCE property located in this workspace but outside the specified item's subgraph and the current Session has read access to that REFERENCE property.

A ConstraintViolationException will be thrown either immediately, on dispatch or on persist, if removing the specified item would violate a node type or implementation-specific constraint. Implementations may differ on when this validation is performed.

A VersionException will be thrown either immediately, on dispatch or on persist, if the parent node of the specified item is read-only due to a checked-in node. Implementations may differ on when this validation is performed.

A LockException will be thrown either immediately, on dispatch or on persist, if a lock prevents the removal of the specified item. Implementations may differ on when this validation is performed.

A PathNotFoundException will be thrown either immediately, on dispatch or on persist, if no accessible item is found at at absPath.

A AccessDeniedException will be thrown either immediately, on dispatch or on persist, if the specified item or an item in its subgraph is currently the target of a REFERENCE property located in this workspace but outside the specified item's subgraph and the current Session does not have read access to that REFERENCE property.

Parameters:
absPath - the absolute path of the item to be removed.
Throws:
VersionException - if the parent node of the item at absPath is read-only due to a checked-in node and this implementation performs this validation immediately.
LockException - if a lock prevents the removal of the specified item and this implementation performs this validation immediately.
ConstraintViolationException - if removing the specified item would violate a node type or implementation-specific constraint and this implementation performs this validation immediately.
PathNotFoundException - if no accessible item is found at absPath and this implementation performs this validation immediately.
AccessDeniedException - if the specified item or an item in its subgraph is currently the target of a REFERENCE property located in this workspace but outside the specified item's subgraph and the current Session does not have read access to that REFERENCE property and this implementation performs this validation immediately.
RepositoryException - if another error occurs.
Since:
JCR 2.0
See Also:
Item.remove()

save

void save()
          throws AccessDeniedException,
                 ItemExistsException,
                 ReferentialIntegrityException,
                 ConstraintViolationException,
                 InvalidItemStateException,
                 VersionException,
                 LockException,
                 NoSuchNodeTypeException,
                 RepositoryException
Validates all pending changes currently recorded in this Session. If validation of all pending changes succeeds, then this change information is cleared from the Session.

If the save occurs outside a transaction, the changes are dispatched and persisted. Upon being persisted the changes become potentially visible to other Sessions bound to the same persitent workspace.

If the save occurs within a transaction, the changes are dispatched but are not persisted until the transaction is committed.

If validation fails, then no pending changes are dispatched and they remain recorded on the Session. There is no best-effort or partial save.

Throws:
AccessDeniedException - if any of the changes to be persisted would violate the access privileges of the this Session. Also thrown if any of the changes to be persisted would cause the removal of a node that is currently referenced by a REFERENCE property that this Session does not have read access to.
ItemExistsException - if any of the changes to be persisted would be prevented by the presence of an already existing item in the workspace.
ConstraintViolationException - if any of the changes to be persisted would violate a node type or restriction. Additionally, a repository may use this exception to enforce implementation- or configuration-dependent restrictions.
InvalidItemStateException - if any of the changes to be persisted conflicts with a change already persisted through another session and the implementation is such that this conflict can only be detected at save-time and therefore was not detected earlier, at change-time.
ReferentialIntegrityException - if any of the changes to be persisted would cause the removal of a node that is currently referenced by a REFERENCE property that this Session has read access to.
VersionException - if the save would make a result in a change to persistent storage that would violate the read-only status of a checked-in node.
LockException - if the save would result in a change to persistent storage that would violate a lock.
NoSuchNodeTypeException - if the save would result in the addition of a node with an unrecognized node type.
RepositoryException - if another error occurs.

refresh

void refresh(boolean keepChanges)
             throws RepositoryException
If keepChanges is false, this method discards all pending changes currently recorded in this Session and returns all items to reflect the current saved state. Outside a transaction this state is simply the current state of persistent storage. Within a transaction, this state will reflect persistent storage as modified by changes that have been saved but not yet committed.

If keepChanges is true then pending change are not discarded but items that do not have changes pending have their state refreshed to reflect the current saved state, thus revealing changes made by other sessions.

Parameters:
keepChanges - a boolean
Throws:
RepositoryException - if an error occurs.

hasPendingChanges

boolean hasPendingChanges()
                          throws RepositoryException
Returns true if this session holds pending (that is, unsaved) changes; otherwise returns false.

Returns:
a boolean
Throws:
RepositoryException - if an error occurs

getValueFactory

ValueFactory getValueFactory()
                             throws UnsupportedRepositoryOperationException,
                                    RepositoryException
This method returns a ValueFactory that is used to create Value objects for use when setting repository properties.

Returns:
a ValueFactory
Throws:
UnsupportedRepositoryOperationException - if writing to the repository is not supported.
RepositoryException - if another error occurs.

hasPermission

boolean hasPermission(java.lang.String absPath,
                      java.lang.String actions)
                      throws RepositoryException
Returns true if this Session has permission to perform the specified actions at the specified absPath and false otherwise.

The actions parameter is a comma separated list of action strings. The following action strings are defined:

  • add_node: If hasPermission(path, "add_node") returns true, then this Session has permission to add a node at path.
  • set_property: If hasPermission(path, "set_property") returns true, then this Session has permission to set (add or change) a property at path.
  • remove: If hasPermission(path, "remove") returns true, then this Session has permission to remove an item at path.
  • read: If hasPermission(path, "read") returns true, then this Session has permission to retrieve (and read the value of, in the case of a property) an item at path.
When more than one action is specified in the actions parameter, this method will only return true if this Session has permission to perform all of the listed actions at the specified path.

The information returned through this method will only reflect the access control status (both JCR defined and implementation-specific) and not other restrictions that may exist, such as node type constraints. For example, even though hasPermission may indicate that a particular Session may add a property at /A/B/C, the node type of the node at /A/B may prevent the addition of a property called C.

Parameters:
absPath - an absolute path.
actions - a comma separated list of action strings.
Returns:
true if this Session has permission to perform the specified actions at the specified absPath.
Throws:
RepositoryException - if an error occurs.
Since:
JCR 2.0

checkPermission

void checkPermission(java.lang.String absPath,
                     java.lang.String actions)
                     throws java.security.AccessControlException,
                            RepositoryException
Determines whether this Session has permission to perform the specified actions at the specified absPath. This method quietly returns if the access request is permitted, or throws a suitable java.security.AccessControlException otherwise.

The actions parameter is a comma separated list of action strings. The following action strings are defined:

  • add_node: If checkPermission(path, "add_node") returns quietly, then this Session has permission to add a node at path, otherwise permission is denied.
  • set_property: If checkPermission(path, "set_property") returns quietly, then this Session has permission to set (add or change) a property at path, otherwise permission is denied.
  • remove: If checkPermission(path, "remove") returns quietly, then this Session has permission to remove an item at path, otherwise permission is denied.
  • read: If checkPermission(path, "read") returns quietly, then this Session has permission to retrieve (and read the value of, in the case of a property) an item at path, otherwise permission is denied.
When more than one action is specified in the actions parameter, this method will only return quietly if this Session has permission to perform all of the listed actions at the specified path.

The information returned through this method will only reflect access control status (both JCR defined and implementation-specific) and not other restrictions that may exist, such as node type constraints. For example, even though checkPermission may indicate that a particular Session may add a property at /A/B/C, the node type of the node at /A/B may prevent the addition of a property called C.

Parameters:
absPath - an absolute path.
actions - a comma separated list of action strings.
Throws:
java.security.AccessControlException - If permission is denied.
RepositoryException - if another error occurs.

hasCapability

boolean hasCapability(java.lang.String methodName,
                      java.lang.Object target,
                      java.lang.Object[] arguments)
                      throws RepositoryException
Checks whether an operation can be performed given as much context as can be determined by the repository, including:
  • Permissions granted to the current user, including access control privileges.
  • Current state of the target object (reflecting locks, checkin/checkout status, retention and hold status etc.).
  • Repository capabilities.
  • Node type-enforced restrictions.
  • Repository configuration-specific restrictions.
The implementation of this method is best effort: returning false guarantees that the operation cannot be performed, but returning true does not guarantee the opposite. The repository implementation should use this to give priority to performance over completeness. An exception should be thrown only for important failures such as loss of connectivity to the back-end.

The implementation of this method is best effort: returning false guarantees that the operation cannot be performed, but returning true does not guarantee the opposite.

The methodName parameter identifies the method in question by its name as defined in the Javadoc.

The target parameter identifies the object on which the specified method is called.

The arguments parameter contains an array of type Object object consisting of the arguments to be passed to the method in question. In cases where a parameter is a Java primitive type it must be converted to its corresponding Java object form.

For example, given a Session S and Node N then

boolean b = S.hasCapability("addNode", N, new Object[]{"foo"});

will result in b == false if a child node called foo cannot be added to the node N within the session S.

Parameters:
methodName - the nakme of the method.
target - the target object of the operation.
arguments - the arguments of the operation.
Returns:
false if the operation cannot be performed, true if the operation can be performed or if the repository cannot determine whether the operation can be performed.
Throws:
RepositoryException - if an error occurs
Since:
JCR 2.0

getImportContentHandler

org.xml.sax.ContentHandler getImportContentHandler(java.lang.String parentAbsPath,
                                                   int uuidBehavior)
                                                   throws PathNotFoundException,
                                                          ConstraintViolationException,
                                                          VersionException,
                                                          LockException,
                                                          RepositoryException
Returns an org.xml.sax.ContentHandler which is used to push SAX events to the repository. If the incoming XML (in the form of SAX events) does not appear to be a JCR system view XML document then it is interpreted as a JCR document view XML document.

The incoming XML is deserialized into a subgraph of items immediately below the node at parentAbsPath.

This method simply returns the ContentHandler without altering the state of the session; the actual deserialization to the session transient space is done through the methods of the ContentHandler. Invalid XML data will cause the ContentHandler to throw a SAXException.

As SAX events are fed into the ContentHandler, the tree of new items is built in the transient storage of the session. In order to dispatch the new content, save must be called. See Workspace.getImportContentHandler(java.lang.String, int) for a workspace-write version of this method.

The flag uuidBehavior governs how the identifiers of incoming nodes are handled:

  • ImportUUIDBehavior.IMPORT_UUID_CREATE_NEW: Incoming identifiers nodes are added in the same way that new node is added with Node.addNode. That is, they are either assigned newly created identifiers upon addition or upon save (depending on the implementation). In either case, identifier collisions will not occur.
  • ImportUUIDBehavior.IMPORT_UUID_COLLISION_REMOVE_EXISTING: If an incoming node has the same identifier as a node already existing in the workspace then the already existing node (and its subgraph) is removed from wherever it may be in the workspace before the incoming node is added. Note that this can result in nodes "disappearing" from locations in the workspace that are remote from the location to which the incoming subgraph is being written. Both the removal and the new addition will be persisted on save.
  • ImportUUIDBehavior.IMPORT_UUID_COLLISION_REPLACE_EXISTING: If an incoming node has the same identifier as a node already existing in the workspace, then the already-existing node is replaced by the incoming node in the same position as the existing node. Note that this may result in the incoming subgraph being disaggregated and "spread around" to different locations in the workspace. In the most extreme case this behavior may result in no node at all being added as child of parentAbsPath. This will occur if the topmost element of the incoming XML has the same identifier as an existing node elsewhere in the workspace. The change will be persisted on save.
  • ImportUUIDBehavior.IMPORT_UUID_COLLISION_THROW: If an incoming node has the same identifier as a node already existing in the workspace then a SAXException is thrown by the ContentHandler during deserialization.
Unlike Workspace.getImportContentHandler, this method does not necessarily enforce all node type constraints during deserialization. Those that would be immediately enforced in a session-write method (Node.addNode, Node.setProperty etc.) of this implementation cause the returned ContentHandler to throw an immediate SAXException during deserialization. All other constraints are checked on save, just as they are in normal write operations. However, which node type constraints are enforced depends upon whether node type information in the imported data is respected, and this is an implementation-specific issue.

A SAXException will also be thrown by the returned ContentHandler during deserialization if uuidBehavior is set to IMPORT_UUID_COLLISION_REMOVE_EXISTING and an incoming node has the same identifier as the node at parentAbsPath or one of its ancestors.

A PathNotFoundException is thrown either immediately, on dispatch or on persist, if no node exists at parentAbsPath. Implementations may differ on when this validation is performed

A ConstraintViolationException is thrown either immediately, on dispatch or on persist, if the new subgraph cannot be added to the node at parentAbsPath due to node-type or other implementation-specific constraints, and this can be determined before the first SAX event is sent. Implementations may differ on when this validation is performed.

A VersionException is thrown either immediately, on dispatch or on persist, if the node at parentAbsPath is read-only due to a check-in. Implementations may differ on when this validation is performed.

A LockException is thrown either immediately, on dispatch or on persist, if a lock prevents the addition of the subgraph. Implementations may differ on when this validation is performed.

Parameters:
parentAbsPath - the absolute path of a node under which (as child) the imported subgraph will be built.
uuidBehavior - a four-value flag that governs how incoming identifiers are handled.
Returns:
an org.xml.sax.ContentHandler whose methods may be called to feed SAX events into the deserializer.
Throws:
PathNotFoundException - if no node exists at parentAbsPath and this implementation performs this validation immediately.
ConstraintViolationException - if the new subgraph cannot be added to the node at parentAbsPath due to node-type or other implementation-specific constraints, and this implementation performs this validation immediately.
VersionException - if the node at parentAbsPath is read-only due to a checked-in node and this implementation performs this validation immediately.
LockException - if a lock prevents the addition of the subgraph and this implementation performs this validation immediately.
RepositoryException - if another error occurs.

importXML

void importXML(java.lang.String parentAbsPath,
               java.io.InputStream in,
               int uuidBehavior)
               throws java.io.IOException,
                      PathNotFoundException,
                      ItemExistsException,
                      ConstraintViolationException,
                      VersionException,
                      InvalidSerializedDataException,
                      LockException,
                      RepositoryException
Deserializes an XML document and adds the resulting item subgraph as a child of the node at parentAbsPath.

If the incoming XML stream does not appear to be a JCR system view XML document then it is interpreted as a document view XML document.

The passed InputStream is closed before this method returns either normally or because of an exception.

The tree of new items is built in the transient storage of the Session. In order to persist the new content, save must be called. The advantage of this through-the-session method is that (depending on what constraint checks the implementation leaves until save) structures that violate node type constraints can be imported, fixed and then saved. The disadvantage is that a large import will result in a large cache of pending nodes in the session. See Workspace.importXML(java.lang.String, java.io.InputStream, int) for a version of this method that does not go through the Session.

The flag uuidBehavior governs how the identifiers of incoming nodes are handled. There are four options:

  • ImportUUIDBehavior.IMPORT_UUID_CREATE_NEW: Incoming nodes are added in the same way that new node is added with Node.addNode. That is, they are either assigned newly created identifiers upon addition or upon save (depending on the implementation, see 4.9.1.1 When Identifiers are Assigned in the specification). In either case, identifier collisions will not occur.
  • ImportUUIDBehavior.IMPORT_UUID_COLLISION_REMOVE_EXISTING: If an incoming node has the same identifier as a node already existing in the workspace then the already existing node (and its subgraph) is removed from wherever it may be in the workspace before the incoming node is added. Note that this can result in nodes "disappearing" from locations in the workspace that are remote from the location to which the incoming subgraph is being written. Both the removal and the new addition will be dispatched on save.
  • ImportUUIDBehavior.IMPORT_UUID_COLLISION_REPLACE_EXISTING: If an incoming node has the same identifier as a node already existing in the workspace, then the already-existing node is replaced by the incoming node in the same position as the existing node. Note that this may result in the incoming subgraph being disaggregated and "spread around" to different locations in the workspace. In the most extreme case this behavior may result in no node at all being added as child of parentAbsPath. This will occur if the topmost element of the incoming XML has the same identifier as an existing node elsewhere in the workspace. The change will be dispatched on save.
  • ImportUUIDBehavior.IMPORT_UUID_COLLISION_THROW: If an incoming node has the same identifier as a node already existing in the workspace then an ItemExistsException is thrown.
Unlike Workspace.importXML(java.lang.String, java.io.InputStream, int), this method does not necessarily enforce all node type constraints during deserialization. Those that would be immediately enforced in a normal write method (Node.addNode, Node.setProperty etc.) of this implementation cause an immediate ConstraintViolationException during deserialization. All other constraints are checked on save, just as they are in normal write operations. However, which node type constraints are enforced depends upon whether node type information in the imported data is respected, and this is an implementation-specific issue.

A ConstraintViolationException will also be thrown immediately if uuidBehavior is set to IMPORT_UUID_COLLISION_REMOVE_EXISTING and an incoming node has the same identifier as the node at parentAbsPath or one of its ancestors.

A PathNotFoundException is thrown either immediately, on dispatch or on persist, if no node exists at parentAbsPath. Implementations may differ on when this validation is performed

A ConstraintViolationException is thrown either immediately, on dispatch or on persist, if the new subgraph cannot be added to the node at parentAbsPath due to node-type or other implementation-specific constraints. Implementations may differ on when this validation is performed.

A VersionException is thrown either immediately, on dispatch or on persist, if the node at parentAbsPath is read-only due to a check-in. Implementations may differ on when this validation is performed.

A LockException is thrown either immediately, on dispatch or on persist, if a lock prevents the addition of the subgraph. Implementations may differ on when this validation is performed.

Parameters:
parentAbsPath - the absolute path of the node below which the deserialized subgraph is added.
in - The Inputstream from which the XML to be deserialized is read.
uuidBehavior - a four-value flag that governs how incoming identifiers are handled.
Throws:
java.io.IOException - if an error during an I/O operation occurs.
PathNotFoundException - if no node exists at parentAbsPath and this implementation performs this validation immediately.
ItemExistsException - if deserialization would overwrite an existing item and this implementation performs this validation immediately.
ConstraintViolationException - if a node type or other implementation-specific constraint is violated that would be checked on a session-write method or if uuidBehavior is set to IMPORT_UUID_COLLISION_REMOVE_EXISTING and an incoming node has the same UUID as the node at parentAbsPath or one of its ancestors.
VersionException - if the node at parentAbsPath is read-only due to a checked-in node and this implementation performs this validation immediately.
InvalidSerializedDataException - if incoming stream is not a valid XML document.
LockException - if a lock prevents the addition of the subgraph and this implementation performs this validation immediately.
RepositoryException - if another error occurs.

exportSystemView

void exportSystemView(java.lang.String absPath,
                      org.xml.sax.ContentHandler contentHandler,
                      boolean skipBinary,
                      boolean noRecurse)
                      throws PathNotFoundException,
                             org.xml.sax.SAXException,
                             RepositoryException
Serializes the node (and if noRecurse is false, the whole subgraph) at absPath into a series of SAX events by calling the methods of the supplied org.xml.sax.ContentHandler. The resulting XML is in the system view form. Note that absPath must be the path of a node, not a property.

If skipBinary is true then any properties of PropertyType.BINARY will be serialized as if they are empty. That is, the existence of the property will be serialized, but its content will not appear in the serialized output (the <sv:value> element will have no content). Note that in the case of multi-value BINARY properties, the number of values in the property will be reflected in the serialized output, though they will all be empty. If skipBinary is false then the actual value(s) of each BINARY property is recorded using Base64 encoding.

If noRecurse is true then only the node at absPath and its properties, but not its child nodes, are serialized. If noRecurse is false then the entire subgraph rooted at absPath is serialized.

If the user lacks read access to some subsection of the specified tree, that section simply does not get serialized, since, from the user's point of view, it is not there.

The serialized output will reflect the state of the current workspace as modified by the state of this Session. This means that pending changes (regardless of whether they are valid according to node type constraints) and all namespace mappings in the namespace registry, as modified by the current session-mappings, are reflected in the output.

The output XML will be encoded in UTF-8.

Parameters:
absPath - The path of the root of the subgraph to be serialized. This must be the path to a node, not a property
contentHandler - The org.xml.sax.ContentHandler to which the SAX events representing the XML serialization of the subgraph will be output.
skipBinary - A boolean governing whether binary properties are to be serialized.
noRecurse - A boolean governing whether the subgraph at absPath is to be recursed.
Throws:
PathNotFoundException - if no node exists at absPath.
org.xml.sax.SAXException - if an error occurs while feeding events to the org.xml.sax.ContentHandler.
RepositoryException - if another error occurs.

exportSystemView

void exportSystemView(java.lang.String absPath,
                      java.io.OutputStream out,
                      boolean skipBinary,
                      boolean noRecurse)
                      throws java.io.IOException,
                             PathNotFoundException,
                             RepositoryException
Serializes the node (and if noRecurse is false, the whole subgraph) at absPath as an XML stream and outputs it to the supplied OutputStream. The resulting XML is in the system view form. Note that absPath must be the path of a node, not a property.

If skipBinary is true then any properties of PropertyType.BINARY will be serialized as if they are empty. That is, the existence of the property will be serialized, but its content will not appear in the serialized output (the <sv:value> element will have no content). Note that in the case of multi-value BINARY properties, the number of values in the property will be reflected in the serialized output, though they will all be empty. If skipBinary is false then the actual value(s) of each BINARY property is recorded using Base64 encoding.

If noRecurse is true then only the node at absPath and its properties, but not its child nodes, are serialized. If noRecurse is false then the entire subgraph rooted at absPath is serialized.

If the user lacks read access to some subsection of the specified tree, that section simply does not get serialized, since, from the user's point of view, it is not there.

The serialized output will reflect the state of the current workspace as modified by the state of this Session. This means that pending changes (regardless of whether they are valid according to node type constraints) and all namespace mappings in the namespace registry, as modified by the current session-mappings, are reflected in the output.

The output XML will be encoded in UTF-8.

It is the responsibility of the caller to close the passed OutputStream.

Parameters:
absPath - The path of the root of the subgraph to be serialized. This must be the path to a node, not a property
out - The OutputStream to which the XML serialization of the subgraph will be output.
skipBinary - A boolean governing whether binary properties are to be serialized.
noRecurse - A boolean governing whether the subgraph at absPath is to be recursed.
Throws:
PathNotFoundException - if no node exists at absPath.
java.io.IOException - if an error during an I/O operation occurs.
RepositoryException - if another error occurs.

exportDocumentView

void exportDocumentView(java.lang.String absPath,
                        org.xml.sax.ContentHandler contentHandler,
                        boolean skipBinary,
                        boolean noRecurse)
                        throws PathNotFoundException,
                               org.xml.sax.SAXException,
                               RepositoryException
Serializes the node (and if noRecurse is false, the whole subgraph) at absPath into a series of SAX events by calling the methods of the supplied org.xml.sax.ContentHandler. The resulting XML is in the document view form. Note that absPath must be the path of a node, not a property.

If skipBinary is true then any properties of PropertyType.BINARY will be serialized as if they are empty. That is, the existence of the property will be serialized, but its content will not appear in the serialized output (the value of the attribute will be empty). If skipBinary is false then the actual value(s) of each BINARY property is recorded using Base64 encoding.

If noRecurse is true then only the node at absPath and its properties, but not its child nodes, are serialized. If noRecurse is false then the entire subgraph rooted at absPath is serialized.

If the user lacks read access to some subsection of the specified tree, that section simply does not get serialized, since, from the user's point of view, it is not there.

The serialized output will reflect the state of the current workspace as modified by the state of this Session. This means that pending changes (regardless of whether they are valid according to node type constraints) and all namespace mappings in the namespace registry, as modified by the current session-mappings, are reflected in the output.

The output XML will be encoded in UTF-8.

Parameters:
absPath - The path of the root of the subgraph to be serialized. This must be the path to a node, not a property
contentHandler - The org.xml.sax.ContentHandler to which the SAX events representing the XML serialization of the subgraph will be output.
skipBinary - A boolean governing whether binary properties are to be serialized.
noRecurse - A boolean governing whether the subgraph at absPath is to be recursed.
Throws:
PathNotFoundException - if no node exists at absPath.
org.xml.sax.SAXException - if an error occurs while feeding events to the org.xml.sax.ContentHandler.
RepositoryException - if another error occurs.

exportDocumentView

void exportDocumentView(java.lang.String absPath,
                        java.io.OutputStream out,
                        boolean skipBinary,
                        boolean noRecurse)
                        throws java.io.IOException,
                               PathNotFoundException,
                               RepositoryException
Serializes the node (and if noRecurse is false, the whole subgraph) at absPath as an XML stream and outputs it to the supplied OutputStream. The resulting XML is in the document view form. Note that absPath must be the path of a node, not a property.

If skipBinary is true then any properties of PropertyType.BINARY will be serialized as if they are empty. That is, the existence of the property will be serialized, but its content will not appear in the serialized output (the value of the attribute will be empty). If skipBinary is false then the actual value(s) of each BINARY property is recorded using Base64 encoding.

If noRecurse is true then only the node at absPath and its properties, but not its child nodes, are serialized. If noRecurse is false then the entire subgraph rooted at absPath is serialized.

If the user lacks read access to some subsection of the specified tree, that section simply does not get serialized, since, from the user's point of view, it is not there.

The serialized output will reflect the state of the current workspace as modified by the state of this Session. This means that pending changes (regardless of whether they are valid according to node type constraints) and all namespace mappings in the namespace registry, as modified by the current session-mappings, are reflected in the output.

The output XML will be encoded in UTF-8.

It is the responsibility of the caller to close the passed OutputStream.

Parameters:
absPath - The path of the root of the subgraph to be serialized. This must be the path to a node, not a property
out - The OutputStream to which the XML serialization of the subgraph will be output.
skipBinary - A boolean governing whether binary properties are to be serialized.
noRecurse - A boolean governing whether the subgraph at absPath is to be recursed.
Throws:
PathNotFoundException - if no node exists at absPath.
java.io.IOException - if an error during an I/O operation occurs.
RepositoryException - if another error occurs.

setNamespacePrefix

void setNamespacePrefix(java.lang.String prefix,
                        java.lang.String uri)
                        throws NamespaceException,
                               RepositoryException
Within the scope of this Session, this method maps uri to prefix. The remapping only affects operations done through this Session. To clear all remappings, the client must acquire a new Session.

All local mappings already present in the Session that include either the specified prefix or the specified uri are removed and the new mapping is added.

Parameters:
prefix - a string
uri - a string
Throws:
NamespaceException - if an attempt is made to map a namespace URI to a prefix beginning with the characters "xml" (in any combination of case) or if an attempt is made to map either the empty prefix or the empty namespace (i.e., if either prefix or uri are the empty string).
RepositoryException - if another error occurs.

getNamespacePrefixes

java.lang.String[] getNamespacePrefixes()
                                        throws RepositoryException
Returns all prefixes currently mapped to URIs in this Session.

Returns:
a string array
Throws:
RepositoryException - if an error occurs

getNamespaceURI

java.lang.String getNamespaceURI(java.lang.String prefix)
                                 throws NamespaceException,
                                        RepositoryException
Returns the URI to which the given prefix is mapped as currently set in this Session.

Parameters:
prefix - a string
Returns:
a string
Throws:
NamespaceException - if the specified prefix is unknown.
RepositoryException - if another error occurs

getNamespacePrefix

java.lang.String getNamespacePrefix(java.lang.String uri)
                                    throws NamespaceException,
                                           RepositoryException
Returns the prefix to which the given uri is mapped as currently set in this Session.

Parameters:
uri - a string
Returns:
a string
Throws:
NamespaceException - if the specified uri is unknown.
RepositoryException - if another error occurs

logout

void logout()
Releases all resources associated with this Session. This method should be called when a Session is no longer needed.

isLive

boolean isLive()
Returns true if this Session object is usable by the client. Otherwise, returns false. A usable Session is one that is neither logged-out, timed-out nor in any other way disconnected from the repository.

Returns:
true if this Session is usable, false otherwise.

addLockToken

void addLockToken(java.lang.String lt)
Deprecated. As of JCR 2.0, LockManager.addLockToken(String) should be used instead.

Adds the specified lock token to this Session. Holding a lock token makes this Session the owner of the lock specified by that particular lock token.

Parameters:
lt - a lock token (a string).

getLockTokens

java.lang.String[] getLockTokens()
Deprecated. As of JCR 2.0, LockManager.getLockTokens() should be used instead.

Returns an array containing all lock tokens currently held by this Session. Note that any such tokens will represent open-scoped locks, since session-scoped locks do not have tokens.

Returns:
an array of lock tokens (strings)

removeLockToken

void removeLockToken(java.lang.String lt)
Deprecated. As of JCR 2.0, LockManager.removeLockToken(String) should be used instead.

Removes the specified lock token from this Session.

Parameters:
lt - a lock token (a string)

getAccessControlManager

AccessControlManager getAccessControlManager()
                                             throws UnsupportedRepositoryOperationException,
                                                    RepositoryException
Returns the access control manager for this Session.

Returns:
the access control manager for this Session
Throws:
UnsupportedRepositoryOperationException - if access control is not supported.
RepositoryException - if another error occurs.
Since:
JCR 2.0

getRetentionManager

RetentionManager getRetentionManager()
                                     throws UnsupportedRepositoryOperationException,
                                            RepositoryException
Returns the retention and hold manager for this Session.

Returns:
the retention manager for this Session.
Throws:
UnsupportedRepositoryOperationException - if retention and hold are not supported.
RepositoryException - if another error occurs.
Since:
JCR 2.0
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD