Node
* and Property
.
*
* @author Markus Nix /a/b[3]/c
).
*
* @return the path of this Item
.
* @throws RepositoryException if an error occurs.
*/
public function getPath();
/**
* Returns the name of this Item
. The name of an item is the
* last element in its path, minus any square-bracket index that may exist.
* If this Item
is the root node of the workspace (i.e., if
* this.getDepth() == 0
), an empty string will be returned.
*
*
* @return the (or a) name of this Item
or an empty string
* if this Item
is the root node.
*
* @throws RepositoryException if an error occurs.
*/
public function getName();
/**
* Returns the ancestor of the specified depth.
* An ancestor of depth x is the Item
that is x
* levels down along the path from the root node to this
* Item
.
*
Item
.
* Item
.
* Item
, which returns this
* Item
itself.
* ItemNotFoundException
is thrown.
*
*
* @param depth An integer, 0 <= depth <= n where n is the depth
* of this Item
.
*
* @return The ancestor of this
* Item
at the specified depth
.
*
* @throws ItemNotFoundException if depth < 0 or
* depth > n where n is the is the depth of
* this item.
*
* @throws AccessDeniedException if the current session does not have
* sufficient access rights to retrieve the specified node.
*
* @throws RepositoryException if another error occurs.
*/
public function getAncestor( $depth );
/**
* Returns the parent of this Item
.
*
* @return The parent of this Item
.
*
* @throws ItemNotFoundException if there is no parent. This only happens
* if this item is the root node of a workspace.
*
* @throws AccessDeniedException if the current session does not have
* sufficient access rights to retrieve the parent of this item.
*
* @throws RepositoryException if another error occurs.
*/
public function getParent();
/**
* Returns the depth of this Item
in the workspace tree.
* Returns the depth below the root node of this Item
* (counting this Item
itself).
*
Item
.
* Item
in the workspace hierarchy.
* @throws RepositoryException if an error occurs.
*/
public function getDepth();
/**
* Returns the Session
through which this Item
* was acquired.
* Every Item
can ultimately be traced back through a series
* of method calls to the call {@link Session#getRootNode}
,
* {@link Session#getItem}
or
* {@link Session#getNodeByUUID}
. This method returns that
* Session
object.
*
* @return the Session
through which this Item
was
* acquired.
* @throws RepositoryException if an error occurs.
*/
public function getSession();
/**
* Indicates whether this Item
is a Node
or a
* Property
.
* Returns true
if this Item
is a Node
;
* Returns false
if this Item
is a Property
.
*
* @return true
if this Item
is a
* Node
, false
if it is a Property
.
*/
public function isNode();
/**
* Returns true
if this is a new item, meaning that it exists only in transient
* storage on the Session
and has not yet been saved. Within a transaction,
* isNew
on an Item
may return false
(because the item
* has been saved) even if that Item
is not in persistent storage (because the
* transaction has not yet been committed).
*
* Note that if an item returns true
on isNew
,
* then by definition is parent will return true
on isModified
.
*
* Note that in level 1 (that is, read-only) implementations,
* this method will always return false
.
*
* @return true
if this item is new; false
otherwise.
*/
public function isNew();
/**
* Returns true
if this Item
has been saved but has subsequently
* been modified through the current session and therefore the state of this item as recorded
* in the session differs from the state of this item as saved. Within a transaction,
* isModified
on an Item
may return false
(because the
* Item
has been saved since the modification) even if the modification in question
* is not in persistent storage (because the transaction has not yet been committed).
*
* Note that in level 1 (that is, read-only) implementations,
* this method will always return false
.
*
* @return true
if this item is modified; false
otherwise.
*/
public function isModified();
/**
* Returns true
if this Item
object
* (the Java object instance) represents the same actual repository item as the
* object otherItem
.
*
* This method does not compare the states of the two items. For example,
* if two Item
objects representing the same actual repository item
* have been retrieved through two different sessions and one has been modified,
* then this method will still return true
for these two objects.
* Note that if two Item
objects representing the same repository item
* are retrieved through the same session they will always reflect the
* same state (see section 6.3.1 Reflecting Item State in the specification
* document) so comparing state is not an issue.
*
* @param otherItem the Item
object to be tested for identity with this Item
.
*
* @return true
if this Item
object and otherItem
represent the same actual repository
* item; false
otherwise.
*/
public function isSame( $otherItem );
/**
* Accepts an ItemVistor
.
* Calls the appropriate ItemVistor
* visit
method of the according to whether this
* Item
is a Node
or a Property
.
*
* @param visitor The ItemVisitor to be accepted.
*
* @throws RepositoryException if an error occurs.
*/
public function accept( ItemVisitor $visitor );
/**
* Validates all pending changes currently recorded in this Session
that apply to this Item
* or any of its descendants (that is, the subtree rooted at this Item). 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.
*
* When an item is saved the item in persistent storage to which pending changes are written is * determined as follows: *
save
of an item that has a UUID will succeed even if that item has,
* in the meantime, been moved in persistent storage to a new location (that is, its path has changed). However, a
* save
of a non-UUID item will fail (throwing an InvalidItemStateException
) if it has,
* in the meantime, been moved in persistent storage to a new location. A save
of a non-UUID item will
* also fail if it has, in addition to being moved, been replaced in its original position by a UUID-bearing item.
*
* Note that save
uses the same rules to match items between transient storage and persistent storage
* as {@link Node#update} does to match nodes between two workspaces.
*
* An AccessDeniedException
will be thrown if any of the changes
* to be persisted would violate the access privileges of this
* Session
or if. 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.
*
* 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 ReferentialIntegrityException
is 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
* has read access to.
*
* 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 RepositoryException
will be thrown if another error
* occurs.
*
* @throws AccessDeniedException if any of the changes to be persisted would violate
* the access privileges of the this Session
. Also thrown if any of the
* changes to be persisted would cause the removal of a node that is currently
* referenced by a REFERENCE
property that this Session
* does not have read access to.
* @throws 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.
* @throws 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.
* @throws 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.
* @throws 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.
* @throws LockException if the save
would result in a
* change to persistent storage that would violate a lock.
* @throws RepositoryException if another error occurs.
*/
public function save();
/**
* If keepChanges
is false
, this method discards all pending changes
* currently recorded in this Session
that apply to this Item or any of its descendants
* (that is, the subtree rooted at this Item)and returns all items to reflect the current
* saved state. Outside a transaction this state is simple 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.
*
* An InvalidItemStateException
is thrown if this Item
object represents a
* workspace item that has been removed (either by this session or another).
*
* @throws InvalidItemStateException if this
* Item
object represents a workspace item that has been
* removed (either by this session or another).
*
* @throws RepositoryException if another error occurs.
*/
public function refresh( $keepChanges );
/**
* Removes this
item (and its subtree).
*
save
must be
* performed that includes the (former) parent of the
* removed item within its scope.
*
* A ConstraintViolationException
will be thrown immediately if
* removing the specified item would violate a node type or implementation-specific
* constraint and that violation can be detected at the time that the remove
* method is called. Otherwise, a ConstraintViolationException
will be
* thrown on save
if the violation can only be detected later, at the time that
* the save
method is called. Note that implementations may differ as to which
* constraints are enforced immediately and which on save
.
*
* A ReferentialIntegrityException
will be thrown on save
* if the item in question is currently the target of a REFERENCE
* property elsewhere in the workspace and the current Session
* has read access to that REFERENCE
property.
*
* An AccessDeniedException
will be thrown on save
* if the item in question is currently the target of a REFERENCE
* property elsewhere in the workspace and the current Session
* does not have read access to that REFERENCE property.
*
* A VersionException
is thrown immediately (not on save
)
* if the parent node of this item is versionable and
* currently checked-in or is non-versionable and its nearest versionable ancestor is checked in.
* Note that if this item itself is checked-in
* (but not its parent) then it can be removed.
*
* A LockException
is thrown if a lock prevents the removal of this item.
*
* @throws VersionException if the parent of this node is versionable and
* currently checked-in (and therefore read-only).
* @throws LockException if a lock prevents the removal of this item.
* @throws ConstraintViolationException if removing the specified item would violate a node type or
* implementation-specific constraint and that violation is detected at the
* time of calling the remove
method.
* @throws RepositoryException if an error occurs.
*/
public function remove();
}
?>