| javax.jcr.Session
| Session | | public interface Session (Code) | | 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(CredentialsString) 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.
|
| Method Summary | |
| public void | addLockToken(String lt)
Adds the specified lock token to this Session. | | public void | checkPermission(String absPath, String actions)
Determines whether this Session has permission to perform the specified actions
at the specified absPath. | | public void | exportDocumentView(String absPath, ContentHandler contentHandler, boolean skipBinary, boolean noRecurse)
Serializes the node (and if noRecurse is false,
the whole subtree) 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. | | public void | exportDocumentView(String absPath, OutputStream out, boolean skipBinary, boolean noRecurse)
Serializes the node (and if noRecurse is false,
the whole subtree) at absPath as an XML stream and outputs it to
the supplied OutputStream. | | public void | exportSystemView(String absPath, ContentHandler contentHandler, boolean skipBinary, boolean noRecurse)
Serializes the node (and if noRecurse is false,
the whole subtree) 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. | | public void | exportSystemView(String absPath, OutputStream out, boolean skipBinary, boolean noRecurse)
Serializes the node (and if noRecurse is false,
the whole subtree) at absPath as an XML stream and outputs it to
the supplied OutputStream. | | public AccessControlManager | getAccessControlManager()
Returns the access control manager for this Session. | | public Object | getAttribute(String name)
Returns the value of the named attribute as an Object, or
null if no attribute of the given name exists.
See
Session.getAttributeNames .
Parameters:
name - the name of an attribute passed in the credentials used toacquire this session. | | public String[] | getAttributeNames()
Returns the names of the attributes set in this session as a result of the
Credentials that were used to acquire it. | | public ContentHandler | getImportContentHandler(String parentAbsPath, int uuidBehavior)
Returns an org.xml.sax.ContentHandler which can be used to
push SAX events into the repository. | | public Item | getItem(String absPath)
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.
If no such property exists a PathNotFoundException is thrown.
This method should only be used if the application does not know whether
the item at the indicated path is property or node. | | public String[] | getLockTokens()
Returns an array containing all lock tokens currently held by this
Session. | | public Lock[] | getLocks()
Returns all locks owned by this session. | | public String | getNamespacePrefix(String uri)
Returns the prefix to which the given uri is mapped as currently
set in this Session. | | public String[] | getNamespacePrefixes()
Returns all prefixes currently mapped to URIs in this Session. | | public String | getNamespaceURI(String prefix)
Returns the URI to which the given prefix is mapped
as currently set in this Session. | | public Node | getNode(String absPath)
Returns the node at the specified absolute path in the workspace.
If no node exists, then a PathNotFoundException is thrown.
Parameters:
absPath - An absolute path. | | public Node | getNodeByIdentifier(String id)
Returns the node specified by the given identifier. | | public Node | getNodeByUUID(String uuid)
Returns the node specifed by the given UUID. | | public Property | getProperty(String absPath)
Returns the property at the specified absolute path in the workspace.
If no property exists, then a PathNotFoundException is thrown.
Parameters:
absPath - An absolute path. | | public Repository | getRepository()
Returns the Repository object through which this session was
acquired. | | public Node | getRootNode()
Returns the root node of the workspace, "/". | | public String | getUserID()
Gets the user ID associated with this Session. | | public ValueFactory | getValueFactory()
This method returns a ValueFactory that is used to create Value objects
for use when setting repository properties. | | public Workspace | getWorkspace()
Returns the Workspace attached to this Session. | | public boolean | hasPendingChanges()
Returns true if this session holds pending (that is, unsaved) changes;
otherwise returns false. | | public Session | impersonate(Credentials credentials)
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. | | public void | importXML(String parentAbsPath, InputStream in, int uuidBehavior)
Deserializes an XML document and adds the resulting item subtree 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. | | public boolean | isLive()
Returns true if this Session object is usable
by the client. | | public boolean | itemExists(String absPath)
Returns true if an item exists at absPath
and this Session has read access to it; otherwise returns
false.
Throws a RepositoryException if absPath is not
a well-formed absolute path.
Parameters:
absPath - An absolute path. | | public void | logout()
Releases all resources associated with this Session. | | public String | move(String srcAbsPath, String destAbsPath)
Moves the node at srcAbsPath (and its entire subtree) to the
new location at destAbsPath. | | public boolean | nodeExists(String absPath)
Returns true if a node exists at absPath
and this Session has read access to it; otherwise returns
false.
Throws a RepositoryException if absPath
is not a well-formed absolute path.
Parameters:
absPath - An absolute path. | | boolean | propertyExists(String absPath)
Returns true if a property exists at absPath
and this Session has read access to it; otherwise returns
false.
Throws a RepositoryException if absPath
is not a well-formed absolute path.
Parameters:
absPath - An absolute path. | | public 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. | | public void | removeLockToken(String lt)
Removes the specified lock token from this Session. | | public void | save()
Validates all pending changes currently recorded in this Session. | | public Node | setActivity(Node activity)
This method is called by the client to set the current activity on the
session. | | public void | setNamespacePrefix(String prefix, String uri)
Within the scope of this Session, this method maps
uri to prefix. |
| addLockToken | | public void addLockToken(String lt) throws LockException, RepositoryException(Code) | | 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.
A LockException is thrown if the specified lock token is
already held by another Session and the implementation does
not support simultaneous ownership of open-scoped locks..
A RepositoryException is thrown if another error occurs.
Parameters:
lt - a lock token (a string)
throws:
LockException - if the specified lock token is already held byanother Session and the implementationdoes not support simultaneous ownership of open-scopedlocks.
throws:
RepositoryException - if another error occurs. |
| checkPermission | | public void checkPermission(String absPath, String actions) throws java.security.AccessControlException, RepositoryException(Code) | | 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 policies
and not other restrictions that may exist. 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.
Parameters:
actions - a comma separated list of action strings.
throws:
java.security.AccessControlException - If permission is denied.
throws:
RepositoryException - if another error occurs. |
| exportDocumentView | | public void exportDocumentView(String absPath, ContentHandler contentHandler, boolean skipBinary, boolean noRecurse) throws PathNotFoundException, SAXException, RepositoryException(Code) | | Serializes the node (and if noRecurse is false,
the whole subtree) 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 subtree
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.
A PathNotFoundException is thrown if no node exists at absPath.
A SAXException is thrown if an error occurs while feeding events to the
ContentHandler.
Parameters:
absPath - The path of the root of the subtree to be serialized.This must be the path to a node, not a property
Parameters:
contentHandler - The org.xml.sax.ContentHandler towhich the SAX events representing the XML serialization of the subtreewill be output.
Parameters:
skipBinary - A boolean governing whether binaryproperties are to be serialized.
Parameters:
noRecurse - A boolean governing whether the subtree atabsPath is to be recursed.
throws:
PathNotFoundException - if no node exists at absPath.
throws:
org.xml.sax.SAXException - if an error occurs while feeding events to theorg.xml.sax.ContentHandler.
throws:
RepositoryException - if another error occurs. |
| exportDocumentView | | public void exportDocumentView(String absPath, OutputStream out, boolean skipBinary, boolean noRecurse) throws IOException, PathNotFoundException, RepositoryException(Code) | | Serializes the node (and if noRecurse is false,
the whole subtree) 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 subtree
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.
An IOException is thrown if an I/O error occurs.
A PathNotFoundException is thrown if no node exists at absPath.
Parameters:
absPath - The path of the root of the subtree to be serialized.This must be the path to a node, not a property
Parameters:
out - The OutputStream to which the XMLserialization of the subtree will be output.
Parameters:
skipBinary - A boolean governing whether binaryproperties are to be serialized.
Parameters:
noRecurse - A boolean governing whether the subtree atabsPath is to be recursed.
throws:
PathNotFoundException - if no node exists at absPath.
throws:
IOException - if an error during an I/O operation occurs.
throws:
RepositoryException - if another error occurs. |
| exportSystemView | | public void exportSystemView(String absPath, ContentHandler contentHandler, boolean skipBinary, boolean noRecurse) throws PathNotFoundException, SAXException, RepositoryException(Code) | | Serializes the node (and if noRecurse is false,
the whole subtree) 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 subtree
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.
A PathNotFoundException is thrown if no node exists at absPath.
A SAXException is thrown if an error occurs while feeding events to the
ContentHandler.
Parameters:
absPath - The path of the root of the subtree to be serialized.This must be the path to a node, not a property
Parameters:
contentHandler - The org.xml.sax.ContentHandler towhich the SAX events representing the XML serialization of the subtreewill be output.
Parameters:
skipBinary - A boolean governing whether binaryproperties are to be serialized.
Parameters:
noRecurse - A boolean governing whether the subtree atabsPath is to be recursed.
throws:
PathNotFoundException - if no node exists at absPath.
throws:
org.xml.sax.SAXException - if an error occurs while feeding events to theorg.xml.sax.ContentHandler.
throws:
RepositoryException - if another error occurs. |
| exportSystemView | | public void exportSystemView(String absPath, OutputStream out, boolean skipBinary, boolean noRecurse) throws IOException, PathNotFoundException, RepositoryException(Code) | | Serializes the node (and if noRecurse is false,
the whole subtree) 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 subtree
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.
An IOException is thrown if an I/O error occurs.
A PathNotFoundException is thrown if no node exists at absPath.
Parameters:
absPath - The path of the root of the subtree to be serialized.This must be the path to a node, not a property
Parameters:
out - The OutputStream to which the XMLserialization of the subtree will be output.
Parameters:
skipBinary - A boolean governing whether binaryproperties are to be serialized.
Parameters:
noRecurse - A boolean governing whether the subtree atabsPath is to be recursed.
throws:
PathNotFoundException - if no node exists at absPath.
throws:
IOException - if an error during an I/O operation occurs.
throws:
RepositoryException - if another error occurs. |
| getAttribute | | public Object getAttribute(String name)(Code) | | Returns the value of the named attribute as an Object, or
null if no attribute of the given name exists.
See
Session.getAttributeNames .
Parameters:
name - the name of an attribute passed in the credentials used toacquire this session. the value of the attribute or null if no attributeof the given name exists. |
| getAttributeNames | | public String[] getAttributeNames()(Code) | | 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.
A string array containing the names of all attributes passed inthe credentials used to acquire this session. |
| getImportContentHandler | | public ContentHandler getImportContentHandler(String parentAbsPath, int uuidBehavior) throws PathNotFoundException, ConstraintViolationException, VersionException, LockException, RepositoryException(Code) | | Returns an org.xml.sax.ContentHandler which can be used to
push SAX events into the repository. If the incoming XML stream (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 subtree 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
persist the new content, save must be called. The advantage
of this through-the-session method is that (depending on which 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.getImportContentHandler for a version of this
method that does not go through the session.
The flag uuidBehavior governs how the identifiers of incoming
(deserialized) nodes are handled. There are four options:
-
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 subtree) 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 subtree 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 subtree 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 normal 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 or on save
if no node exists at parentAbsPath. Implementations may differ on when this
validation is performed
A ConstraintViolationException is thrown either immediately or on save
if the new subtree 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 or on save if the node at
parentAbsPath is versionable and checked-in, or is non-versionable but
its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.
A LockException is thrown either immediately or on save
if a lock prevents the addition of the subtree. Implementations may differ on when this validation is performed.
Parameters:
parentAbsPath - the absolute path of a node under which (as child) the imported subtree will bebuilt.
Parameters:
uuidBehavior - a four-value flag that governs how incoming identifiers are handled. an org.xml.sax.ContentHandler whose methods may be called to feed SAX eventsinto the deserializer.
throws:
PathNotFoundException - if no node exists at parentAbsPath and thisimplementation performs this validation immediately instead of waiting until save.
throws:
ConstraintViolationException - if the new subtree cannot be added to the node atparentAbsPath due to node-type or other implementation-specific constraints,and this implementation performs this validation immediately instead of waiting until save.
throws:
VersionException - if the node at parentAbsPath is versionableand checked-in, or is non-versionable but its nearest versionable ancestor is checked-in and thisimplementation performs this validation immediately instead of waiting until save..
throws:
LockException - if a lock prevents the addition of the subtree and thisimplementation performs this validation immediately instead of waiting until save..
throws:
RepositoryException - if another error occurs. |
| getItem | | public Item getItem(String absPath) throws PathNotFoundException, RepositoryException(Code) | | 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.
If no such property exists a PathNotFoundException is thrown.
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
Session.getNode or
Session.getProperty should be used, as appropriate. In many repository
implementations the node and property-specific methods are likely to be
more efficient than getItem.
A RepositoryException is thrown if another error occurs.
Parameters:
absPath - An absolute path. the specified Item.
throws:
PathNotFoundException - if the specified path cannot be found.
throws:
RepositoryException - if another error occurs. |
| getLockTokens | | public String[] getLockTokens()(Code) | | 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.
an array of lock tokens (strings) |
| getLocks | | public Lock[] getLocks()(Code) | | Returns all locks owned by this session.
an array of Locks
since:
JCR 2.0 |
| getNodeByIdentifier | | public Node getNodeByIdentifier(String id) throws ItemNotFoundException, RepositoryException(Code) | | Returns the node specified by the given identifier. Applies to both
referenceable and non-referenceable nodes.
An ItemNotFoundException is thrown if no node with the
specified identifier exists. This exception is also thrown if this
Session does not have read access to the node with the
specified identifier.
A RepositoryException is thrown if another error occurs.
Parameters:
id - An identifier. A Node.
throws:
ItemNotFoundException - if the specified identifier is not found.
throws:
RepositoryException - if another error occurs.
since:
JCR 2.0 |
| getRepository | | public Repository getRepository()(Code) | | Returns the Repository object through which this session was
acquired.
a Repository object. |
| getRootNode | | public Node getRootNode() throws RepositoryException(Code) | | Returns the root node of the workspace, "/". This node is the main
access point to the content of the workspace.
A RepositoryException is thrown if an error occurs.
The root node of the workspace: a Node object.
throws:
RepositoryException - if an error occurs. |
| getUserID | | public String getUserID()(Code) | | 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.
the user ID associated with this Session. |
| hasPendingChanges | | public boolean hasPendingChanges() throws RepositoryException(Code) | | Returns true if this session holds pending (that is, unsaved) changes;
otherwise returns false.
a boolean
throws:
RepositoryException - if an error occurs |
| impersonate | | public Session impersonate(Credentials credentials) throws LoginException, RepositoryException(Code) | | 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.
A LoginException is thrown if this session does not have
sufficient permissions to perform the operation.
A RepositoryException is thrown if another error occurs.
Parameters:
credentials - A Credentials object a Session object
throws:
LoginException - if the current session does not have sufficientpermissions to perform the operation.
throws:
RepositoryException - if another error occurs. |
| importXML | | public void importXML(String parentAbsPath, InputStream in, int uuidBehavior) throws IOException, PathNotFoundException, ItemExistsException, ConstraintViolationException, VersionException, InvalidSerializedDataException, LockException, RepositoryException(Code) | | Deserializes an XML document and adds the resulting item subtree 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 for a version of this method that does not go
through the Session.
The flag uuidBehavior governs how the identifiers of incoming
(deserialized) 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 subtree) 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
subtree 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 subtree 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 only 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 an
ItemExistsException is thrown.
Unlike
Workspace.importXML , 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 ((see
5.4.3 Respecting Property Semantics in the specification).
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 or on save
if no node exists at parentAbsPath. Implementations may differ on when this
validation is performed
A ConstraintViolationException is thrown either immediately or on save
if the new subtree 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 or on save if the node at
parentAbsPath is versionable and checked-in, or is non-versionable but
its nearest versionable ancestor is checked-in. Implementations may differ on when this validation is performed.
A LockException is thrown either immediately or on save
if a lock prevents the addition of the subtree. Implementations may differ on when this validation is performed.
Parameters:
parentAbsPath - the absolute path of the node below which the deserialized subtree is added.
Parameters:
in - The Inputstream from which the XML to be deserilaized is read.
Parameters:
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.
throws:
PathNotFoundException - if no node exists at parentAbsPath and thisimplementation performs this validation immediately instead of waiting until save..
throws:
ItemExistsException - if deserialization would overwrite an existing item and thisimplementation performs this validation immediately instead of waiting until save..
throws:
ConstraintViolationException - if a node type or other implementation-specificconstraint is violated that would be checked on a normal write method or ifuuidBehavior is set to IMPORT_UUID_COLLISION_REMOVE_EXISTINGand an incoming node has the same UUID as the node at parentAbsPath or oneof its ancestors.
throws:
VersionException - if the node at parentAbsPath is versionableand checked-in, or its nearest versionable ancestor is checked-in and thisimplementation performs this validation immediately instead of waiting until save..
throws:
InvalidSerializedDataException - if incoming stream is not a valid XML document.
throws:
LockException - if a lock prevents the addition of the subtree and thisimplementation performs this validation immediately instead of waiting until save..
throws:
RepositoryException - is another error occurs. |
| isLive | | public boolean isLive()(Code) | | 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.
true if this Session is usable,false otherwise. |
| itemExists | | public boolean itemExists(String absPath) throws RepositoryException(Code) | | Returns true if an item exists at absPath
and this Session has read access to it; otherwise returns
false.
Throws a RepositoryException if absPath is not
a well-formed absolute path.
Parameters:
absPath - An absolute path. a boolean
throws:
RepositoryException - if absPath is not a well-formedabsolute path. |
| logout | | public void logout()(Code) | | Releases all resources associated with this Session. This method should be called when a
Session is no longer needed.
|
| move | | public String move(String srcAbsPath, String destAbsPath) throws ItemExistsException, PathNotFoundException, VersionException, ConstraintViolationException, LockException, RepositoryException(Code) | | Moves the node at srcAbsPath (and its entire subtree) to the
new location at destAbsPath. Returns the path of the node at
its new position. Note that the returned path will indicate the resulting
same-name sibling index of the destination (if necessary), unlike the
supplied destAbsPath parameter (see below).
In order to persist the change, a save
must be called on either the session or a common ancestor to both the source and destination locations.
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 or on save
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
save if an attempt is made to seperately save
either the source or destination node.
Note that this behaviour differs from that of
Workspace.move , which operates directly in the persistent
workspace and does not require a save.
The destAbsPath provided must not have an index on its final
element. If it does then a RepositoryException is thrown.
Strictly speaking, the destAbsPath parameter is actually an
absolute path to the parent node of the new location, appended
with the new name desired for the moved node. It does not specify
a position within the child node ordering (if such ordering is
supported). 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. The resulting position within a same-name sibling set
can, however, be determined from the path returned by this method, which
will include an index if one is required.
This method cannot be used to move just an individual property by itself.
It moves an entire node and its subtree (including, of course, any properties
contained therein).
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 or on save.
Implementations may differ on when this validation is performed.
An ItemExistsException is thrown either immediately or on save
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 or on save
if the parent node of destAbsPath or the parent node of srcAbsPath] is versionable and
checked-in, or is non-versionable and its nearest versionable ancestor is checked-in.
Implementations may differ on when this validation is performed.
A LockException is thrown either immediately or on save
if a lock prevents the move. Implementations may differ on when this validation is performed.
Parameters:
srcAbsPath - the root of the subtree to be moved.
Parameters:
destAbsPath - the location to which the subtree is to be moved. the path of the node at its new position.
throws:
ItemExistsException - if a node already exists at destAbsPathand same-name siblings are not allowed.
throws:
PathNotFoundException - if either srcAbsPath or destAbsPath cannot be found and thisimplementation performs this validation immediately instead of waiting until save.
throws:
VersionException - if the parent node of destAbsPath or the parent node of srcAbsPathis versionable and checked-in, or or is non-verionable and its nearest versionable ancestor is checked-in and thisimplementation performs this validation immediately instead of waiting until save.
throws:
ConstraintViolationException - if a node-type or other constraint violation is detected immediately and thisimplementation performs this validation immediately instead of waiting until save.
throws:
LockException - if the move operation would violate a lock and thisimplementation performs this validation immediately instead of waiting until save.
throws:
RepositoryException - if the last element of destAbsPath has an index or if another error occurs. |
| nodeExists | | public boolean nodeExists(String absPath) throws RepositoryException(Code) | | Returns true if a node exists at absPath
and this Session has read access to it; otherwise returns
false.
Throws a RepositoryException if absPath
is not a well-formed absolute path.
Parameters:
absPath - An absolute path. a boolean
throws:
RepositoryException - if absPath is not a well-formedabsolute path.
since:
JCR 2.0 |
| propertyExists | | boolean propertyExists(String absPath) throws RepositoryException(Code) | | Returns true if a property exists at absPath
and this Session has read access to it; otherwise returns
false.
Throws a RepositoryException if absPath
is not a well-formed absolute path.
Parameters:
absPath - An absolute path. a boolean
throws:
RepositoryException - if absPath is not a well-formedabsolute path.
since:
JCR 2.0 |
| refresh | | public void refresh(boolean keepChanges) throws RepositoryException(Code) | | 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. |
| removeLockToken | | public void removeLockToken(String lt) throws LockException, RepositoryException(Code) | | Removes the specified lock token from this Session.
A LockException is thrown if this Session does
not hold the specified lock token.
A RepositoryException is thrown if another error occurs.
Parameters:
lt - a lock token (a string)
throws:
LockException - if this Session does not hold thespecified lock token.
throws:
RepositoryException - if another error occurs. |
| save | | public void save() throws AccessDeniedException, ItemExistsException, ConstraintViolationException, InvalidItemStateException, VersionException, LockException, NoSuchNodeTypeException, RepositoryException(Code) | | 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 persisted and thus
made visible to other Sessions. If the save occurs within a transaction,
the changes are not persisted until the transaction is committed.
If validation fails, then no pending changes are saved and they remain recorded on the Session.
There is no best-effort or partial save.
The item in persistent storage to which a transient item is saved is
determined by matching identifiers and paths.
An AccessDeniedException will be thrown if any of the changes
to be persisted would violate the access privileges of this
Session.
If any of the changes to be persisted would cause the removal of a node
that is currently the target of a REFERENCE property then a
ReferentialIntegrityException is thrown, provided that this Session has
read access to that REFERENCE property. If, on the other hand, this
Session does not have read access to the REFERENCE property in question,
then an AccessDeniedException is thrown instead.
An ItemExistsException will be thrown if any of the changes
to be persisted would be prevented by the presence of an already existing
item in the workspace.
A ConstraintViolationException will be thrown if any of the
changes to be persisted would violate a node type restriction.
Additionally, a repository may use this exception to enforce
implementation- or configuration-dependant restrictions.
An InvalidItemStateException is thrown 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.
A VersionException is thrown 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.
A LockException is thrown if the save would result
in a change to persistent storage that would violate a lock.
A NoSuchNodeTypeException is thrown if the save would result in the
addition of a node with an unrecognized node type.
A RepositoryException will be thrown if another error
occurs.
throws:
AccessDeniedException - if any of the changes to be persisted would violatethe access privileges of the this Session. Also thrown if any of thechanges to be persisted would cause the removal of a node that is currentlyreferenced by a REFERENCE property that this Sessiondoes not have read access to.
throws:
ItemExistsException - if any of the changesto be persisted would be prevented by the presence of an already existingitem in the workspace.
throws:
ConstraintViolationException - if any of the changes to be persisted wouldviolate a node type or restriction. Additionally, a repository may use thisexception to enforce implementation- or configuration-dependent restrictions.
throws:
InvalidItemStateException - if any of thechanges to be persisted conflicts with a change already persistedthrough another session and the implementation is such that thisconflict can only be detected at save-time and therefore was notdetected earlier, at change-time.
throws:
ReferentialIntegrityException - if any of thechanges to be persisted would cause the removal of a node that is currentlyreferenced by a REFERENCE property that this Sessionhas read access to.
throws:
VersionException - if the save would make a result ina change to persistent storage that would violate the read-only status of achecked-in node.
throws:
LockException - if the save would result in achange to persistent storage that would violate a lock.
throws:
NoSuchNodeTypeException - if the save would result in theaddition of a node with an unrecognized node type.
throws:
RepositoryException - if another error occurs. |
| setActivity | | public Node setActivity(Node activity) throws UnsupportedRepositoryOperationException, RepositoryException(Code) | | This method is called by the client to set the current activity on the
session. Changing the current activity is done by calling setActivity
again. Cancelling the current activity (so that the session has no
current activity) is done by calling setActivity(null).
The activity Node is returned.
An UnsupportedRepositoryOperationException is thrown if the
repsoitory does not support activities or if activity is not
a nt:activity node.
Parameters:
activity - an activity node the activity node
throws:
UnsupportedRepositoryOperationException - if the repository doesnot support activities or if activity is not ant:activity node.
throws:
RepositoryException - if another error occurs.
since:
JCR 2.0 |
| setNamespacePrefix | | public void setNamespacePrefix(String prefix, String uri) throws NamespaceException, RepositoryException(Code) | | 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.
A NamespaceException will be thrown if an attempt is made to
map a namespace URI to a prefix beginning with the characters
"xml" (in any combination of case).
A NamespaceException will be thrown 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).
Parameters:
prefix - a string
Parameters:
uri - a string
throws:
NamespaceException - if the local mapping cannot be done.
throws:
RepositoryException - if another error occurs. |
|
|