javax.jcr
Interface Item

All Known Subinterfaces:

Node, Property, Version, VersionHistory

public interface Item

The Item is the base interface of Node and Property.

Method Summary

void	accept(ItemVisitor visitor) Accepts an ItemVisitor.
Item	getAncestor(int depth) Returns the ancestor of this Item at the specified depth.
int	getDepth() Returns the depth of this Item in the workspace item graph.
java.lang.String	getName() Returns the name of this Item in qualified form.
Node	getParent() Returns the parent of this Item.
java.lang.String	getPath() Returns the normalized absolute path to this item.
Session	getSession() Returns the Session through which this Item was acquired.
boolean	isModified() 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.
boolean	isNew() 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.
boolean	isNode() Indicates whether this Item is a Node or a Property.
boolean	isSame(Item otherItem) Returns true if this Item object (the Java object instance) represents the same actual workspace item as the object otherItem.
void	refresh(boolean keepChanges) 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 subgraph rooted at this Item)and returns all items to reflect the current saved state.
void	remove() Removes this item (and its subgraph).
void	save() Deprecated. As of JCR 2.0, Session.save() should be used instead.

Method Detail

getPath

java.lang.String getPath()
                         throws RepositoryException

Returns the normalized absolute path to this item.

Returns:

the normalized absolute path of this Item.

Throws:

RepositoryException - if an error occurs.

getName

java.lang.String getName()
                         throws RepositoryException

Returns the name of this Item in qualified form. If this Item is the root node of the workspace, an empty string is returned.

Returns:

the name of this Item in qualified form or an empty string if this Item is the root node of a workspace.

Throws:

RepositoryException - if an error occurs.

getAncestor

Item getAncestor(int depth)
                 throws ItemNotFoundException,
                        AccessDeniedException,
                        RepositoryException

Returns the ancestor of this Item at 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.

• depth = 0 returns the root node of a workspace.
• depth = 1 returns the child of the root node along the path to this Item.
• depth = 2 returns the grandchild of the root node along the path to this Item.
• And so on to depth = n, where n is the depth of this Item, which returns this Item itself.

If this node has more than one path (i.e., if it is a descendant of a shared node) then the path used to define the ancestor is implementaion-dependent.

Parameters:

depth - An integer, 0 <= depth <= n where n is the depth of this Item.

Returns:

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.

AccessDeniedException - if the current session does not have sufficent access to retrieve the specified node.

RepositoryException - if another error occurs.

getParent

Node getParent()
               throws ItemNotFoundException,
                      AccessDeniedException,
                      RepositoryException

Returns the parent of this Item.

Returns:

The parent of this Item.

Throws:

ItemNotFoundException - if this Item is the root node of a workspace.

AccessDeniedException - if the current session does not have sufficent access to retrieve the parent of this item.

RepositoryException - if another error occurs.

getDepth

int getDepth()
             throws RepositoryException

Returns the depth of this Item in the workspace item graph.

• The root node returns 0.
• A property or child node of the root node returns 1.
• A property or child node of a child node of the root returns 2.
• And so on to this Item.

Returns:

The depth of this Item in the workspace item graph.

Throws:

RepositoryException - if an error occurs.

getSession

Session getSession()
                   throws RepositoryException

Returns the Session through which this Item was acquired.

Returns:

the Session through which this Item was acquired.

Throws:

RepositoryException - if an error occurs.

isNode

boolean isNode()

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.

Returns:

true if this Item is a Node, false if it is a Property.

isNew

boolean isNew()

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 read-only implementations, this method will always return false.

Returns:

true if this item is new; false otherwise.

isModified

boolean isModified()

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 read-only implementations, this method will always return false.

Returns:

true if this item is modified; false otherwise.

isSame

boolean isSame(Item otherItem)
               throws RepositoryException

Returns true if this Item object (the Java object instance) represents the same actual workspace item as the object otherItem.

Two Item objects represent the same workspace item if and only if all the following are true:

• Both objects were acquired through Session objects that were created by the same Repository object.
• Both objects were acquired through Session objects bound to the same repository workspace.
• The objects are either both Node objects or both Property objects.
• If they are Node objects, they have the same identifier.
• If they are Property objects they have identical names and isSame is true of their parent nodes.

This method does not compare the states of the two items. For example, if two Item objects representing the same actual workspace item have been retrieved through two different sessions and one has been modified, then this method will still return true when comparing these two objects. Note that if two Item objects representing the same workspace item are retrieved through the same session they will always reflect the same state.

Parameters:

otherItem - the Item object to be tested for identity with this Item.

Returns:

true if this Item object and otherItem represent the same actual repository item; false otherwise.

Throws:

RepositoryException - if an error occurs.

accept

void accept(ItemVisitor visitor)
            throws RepositoryException

Accepts an ItemVisitor. Calls the appropriate ItemVisitor visit method of the according to whether this Item is a Node or a Property.

Parameters:

visitor - The ItemVisitor to be accepted.

Throws:

RepositoryException - if an error occurs.

save

void save()
          throws AccessDeniedException,
                 ItemExistsException,
                 ConstraintViolationException,
                 InvalidItemStateException,
                 ReferentialIntegrityException,
                 VersionException,
                 LockException,
                 NoSuchNodeTypeException,
                 RepositoryException

Deprecated. As of JCR 2.0, Session.save() should be used instead.

Validates all pending changes currently recorded in this Session that apply to this Item or any of its descendants (that is, the subgraph 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.

The item in persistent storage to which a transient item is saved is

Throws:

AccessDeniedException - if any of the changes to be persisted would exceed the access capabilities of the the current 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 the current session does not have read access to.

ItemExistsException - if any of the changes to be persisted would be prevented by the presence of an already existing item in the workspace.

ConstraintViolationException - if any of the changes to be persisted would violate a node type or restriction. Additionally, a repository may use this exception to enforce implementation- or configuration-dependent restrictions.

InvalidItemStateException - if any of the changes to be persisted conflicts with a change already persisted through another session and the implementation is such that this conflict can only be detected at save-time and therefore was not detected earlier, at change-time.

ReferentialIntegrityException - if any of the changes to be persisted would cause the removal of a node that is currently referenced by a REFERENCE property that this Session has read access to.

VersionException - if the save would make a result in a change to persistent storage that would violate the read-only status of a checked-in node.

LockException - if the save would result in a change to persistent storage that would violate a lock.

NoSuchNodeTypeException - if the save would result in the addition of a node with an unrecognized node type.

RepositoryException - if another error occurs.

refresh

void refresh(boolean keepChanges)
             throws InvalidItemStateException,
                    RepositoryException

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 subgraph 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.

Parameters:

keepChanges - a boolean

Throws:

InvalidItemStateException - if this Item object represents a workspace item that has been removed (either by this session or another).

RepositoryException - if another error occurs.

remove

void remove()
            throws VersionException,
                   LockException,
                   ConstraintViolationException,
                   AccessDeniedException,
                   RepositoryException

Removes this item (and its subgraph).

To persist a removal, a save must be performed that includes the (former) parent of the removed item within its scope.

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.

Throws:

VersionException - if the parent node of this item is versionable and checked-in or is non-versionable but its nearest versionable ancestor is checked-in and this implementation performs this validation immediately instead of waiting until save.

LockException - if a lock prevents the removal of this item and this implementation performs this validation immediately instead of waiting until save.

ConstraintViolationException - if removing the specified item would violate a node type or implementation-specific constraint and this implementation performs this validation immediately instead of waiting until save.

AccessDeniedException - if this item or an item in its subgraph is currently the target of a REFERENCE property located in this workspace but outside this item's subgraph and the current Session does not have read access to that REFERENCE property or if the current Session does not have sufficent privileges to remove the item.

RepositoryException - if another error occurs.

See Also:

Session.removeItem(String)