|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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 |
---|
static final java.lang.String ACTION_READ
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).
hasPermission(String, String)
,
checkPermission(String, String)
,
Constant Field Valuesstatic final java.lang.String ACTION_ADD_NODE
add_node
action string, used to
determine if this Session
has permission to add a new node.
hasPermission(String, String)
,
checkPermission(String, String)
,
Constant Field Valuesstatic final java.lang.String ACTION_SET_PROPERTY
set_property
action string, used
to determine if this Session
has permission to set (add or
modify) a property.
hasPermission(String, String)
,
checkPermission(String, String)
,
Constant Field Valuesstatic final java.lang.String ACTION_REMOVE
remove
action string, used to
determine if this Session
has permission to remove an item.
hasPermission(String, String)
,
checkPermission(String, String)
,
Constant Field ValuesMethod Detail |
---|
Repository getRepository()
Repository
object through which this session was
acquired.
Repository
object.java.lang.String getUserID()
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
.
Session
.java.lang.String[] getAttributeNames()
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.
java.lang.Object getAttribute(java.lang.String name)
Object
, or
null
if no attribute of the given name exists. See getAttributeNames()
.
name
- the name of an attribute passed in the credentials used to
acquire this session.
null
if no attribute
of the given name exists.Workspace getWorkspace()
Workspace
attached to this
Session
.
Workspace
object.Node getRootNode() throws RepositoryException
Node
object.
RepositoryException
- if an error occurs.Session impersonate(Credentials credentials) throws LoginException, RepositoryException
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
.
credentials
- A Credentials
object
Session
object
LoginException
- if the current session does not have sufficient
access to perform the operation.
RepositoryException
- if another error occurs.Node getNodeByUUID(java.lang.String uuid) throws ItemNotFoundException, RepositoryException
getNodeByIdentifier(String)
should be
used instead.
mix:referenceable
uuid
- A universally unique identifier.
Node
.
ItemNotFoundException
- if the specified UUID is not found.
RepositoryException
- if another error occurs.Node getNodeByIdentifier(java.lang.String id) throws ItemNotFoundException, RepositoryException
id
- An identifier.
Node
.
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
Item getItem(java.lang.String absPath) throws PathNotFoundException, RepositoryException
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
.
absPath
- An absolute path.
Item
.
PathNotFoundException
- if no accessible item is found at the
specified path.
RepositoryException
- if another error occurs.Node getNode(java.lang.String absPath) throws PathNotFoundException, RepositoryException
absPath
- An absolute path.
Node
.
PathNotFoundException
- If no accessible node is found at the
specifed path.
RepositoryException
- If another error occurs.Property getProperty(java.lang.String absPath) throws PathNotFoundException, RepositoryException
absPath
- An absolute path.
Property
.
PathNotFoundException
- If no accessible property is found at the
specified path.
RepositoryException
- if another error occurs.boolean itemExists(java.lang.String absPath) throws RepositoryException
true
if an item exists at absPath
and
this Session
has read access to it; otherwise returns
false
.
absPath
- An absolute path.
boolean
RepositoryException
- if absPath
is not a well-formed
absolute path.boolean nodeExists(java.lang.String absPath) throws RepositoryException
true
if a node exists at absPath
and
this Session
has read access to it; otherwise returns
false
.
absPath
- An absolute path.
boolean
RepositoryException
- if absPath
is not a well-formed
absolute path.boolean propertyExists(java.lang.String absPath) throws RepositoryException
true
if a property exists at absPath
and this Session
has read access to it; otherwise returns
false
.
absPath
- An absolute path.
boolean
RepositoryException
- if absPath
is not a well-formed
absolute path.void move(java.lang.String srcAbsPath, java.lang.String destAbsPath) throws ItemExistsException, PathNotFoundException, VersionException, ConstraintViolationException, LockException, RepositoryException
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
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.
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.
srcAbsPath
- the root of the subgraph to be moved.destAbsPath
- the location to which the subgraph is to be moved.
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.
void removeItem(java.lang.String absPath) throws VersionException, LockException, ConstraintViolationException, AccessDeniedException, RepositoryException
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.
absPath
- the absolute path of the item to be removed.
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.Item.remove()
void save() throws AccessDeniedException, ItemExistsException, ReferentialIntegrityException, ConstraintViolationException, InvalidItemStateException, VersionException, LockException, NoSuchNodeTypeException, RepositoryException
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
.
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.void refresh(boolean keepChanges) throws RepositoryException
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.
keepChanges
- a boolean
RepositoryException
- if an error occurs.boolean hasPendingChanges() throws RepositoryException
true
if this session holds pending (that is,
unsaved) changes; otherwise returns false
.
RepositoryException
- if an error occursValueFactory getValueFactory() throws UnsupportedRepositoryOperationException, RepositoryException
ValueFactory
that is used to create
Value
objects for use when setting repository properties.
ValueFactory
UnsupportedRepositoryOperationException
- if writing to the
repository is not supported.
RepositoryException
- if another error occurs.boolean hasPermission(java.lang.String absPath, java.lang.String actions) throws RepositoryException
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
. 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
.
absPath
- an absolute path.actions
- a comma separated list of action strings.
true
if this Session
has permission to
perform the specified actions at the specified
absPath
.
RepositoryException
- if an error occurs.void checkPermission(java.lang.String absPath, java.lang.String actions) throws java.security.AccessControlException, RepositoryException
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. 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
.
absPath
- an absolute path.actions
- a comma separated list of action strings.
java.security.AccessControlException
- If permission is denied.
RepositoryException
- if another error occurs.boolean hasCapability(java.lang.String methodName, java.lang.Object target, java.lang.Object[] arguments) throws RepositoryException
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
.
methodName
- the nakme of the method.target
- the target object of the operation.arguments
- the arguments of the operation.
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.
RepositoryException
- if an error occursorg.xml.sax.ContentHandler getImportContentHandler(java.lang.String parentAbsPath, int uuidBehavior) throws PathNotFoundException, ConstraintViolationException, VersionException, LockException, RepositoryException
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. 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.
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.
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.void importXML(java.lang.String parentAbsPath, java.io.InputStream in, int uuidBehavior) throws java.io.IOException, PathNotFoundException, ItemExistsException, ConstraintViolationException, VersionException, InvalidSerializedDataException, LockException, RepositoryException
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. 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.
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.
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.void exportSystemView(java.lang.String absPath, org.xml.sax.ContentHandler contentHandler, boolean skipBinary, boolean noRecurse) throws PathNotFoundException, org.xml.sax.SAXException, RepositoryException
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.
absPath
- The path of the root of the subgraph to be serialized.
This must be the path to a node, not a propertycontentHandler
- 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.
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.void exportSystemView(java.lang.String absPath, java.io.OutputStream out, boolean skipBinary, boolean noRecurse) throws java.io.IOException, PathNotFoundException, RepositoryException
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
.
absPath
- The path of the root of the subgraph to be serialized.
This must be the path to a node, not a propertyout
- 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.
PathNotFoundException
- if no node exists at absPath
.
java.io.IOException
- if an error during an I/O operation occurs.
RepositoryException
- if another error occurs.void exportDocumentView(java.lang.String absPath, org.xml.sax.ContentHandler contentHandler, boolean skipBinary, boolean noRecurse) throws PathNotFoundException, org.xml.sax.SAXException, RepositoryException
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.
absPath
- The path of the root of the subgraph to be serialized.
This must be the path to a node, not a propertycontentHandler
- 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.
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.void exportDocumentView(java.lang.String absPath, java.io.OutputStream out, boolean skipBinary, boolean noRecurse) throws java.io.IOException, PathNotFoundException, RepositoryException
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
.
absPath
- The path of the root of the subgraph to be serialized.
This must be the path to a node, not a propertyout
- 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.
PathNotFoundException
- if no node exists at absPath
.
java.io.IOException
- if an error during an I/O operation occurs.
RepositoryException
- if another error occurs.void setNamespacePrefix(java.lang.String prefix, java.lang.String uri) throws NamespaceException, RepositoryException
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.
prefix
- a stringuri
- a string
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.java.lang.String[] getNamespacePrefixes() throws RepositoryException
Session
.
RepositoryException
- if an error occursjava.lang.String getNamespaceURI(java.lang.String prefix) throws NamespaceException, RepositoryException
prefix
is mapped as
currently set in this Session
.
prefix
- a string
NamespaceException
- if the specified prefix
is
unknown.
RepositoryException
- if another error occursjava.lang.String getNamespacePrefix(java.lang.String uri) throws NamespaceException, RepositoryException
uri
is mapped as
currently set in this Session
.
uri
- a string
NamespaceException
- if the specified uri
is unknown.
RepositoryException
- if another error occursvoid logout()
Session
. This
method should be called when a Session
is no longer needed.
boolean isLive()
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.void addLockToken(java.lang.String lt)
LockManager.addLockToken(String)
should be used instead.
Session
. Holding a
lock token makes this Session
the owner of the lock
specified by that particular lock token.
lt
- a lock token (a string).java.lang.String[] getLockTokens()
LockManager.getLockTokens()
should be
used instead.
Session
. Note that any such tokens will represent
open-scoped locks, since session-scoped locks do not have tokens.
void removeLockToken(java.lang.String lt)
LockManager.removeLockToken(String)
should be used instead.
Session
.
lt
- a lock token (a string)AccessControlManager getAccessControlManager() throws UnsupportedRepositoryOperationException, RepositoryException
Session
.
Session
UnsupportedRepositoryOperationException
- if access control is not
supported.
RepositoryException
- if another error occurs.RetentionManager getRetentionManager() throws UnsupportedRepositoryOperationException, RepositoryException
Session
.
Session
.
UnsupportedRepositoryOperationException
- if retention and hold are
not supported.
RepositoryException
- if another error occurs.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |