Package javax.jcr

Interface Item

All Known Subinterfaces:
JackrabbitNode, Node, Property, Version, VersionHistory
All Known Implementing Classes:
AbstractItem, AbstractNode, AbstractProperty
public interface Item
The Item is the base interface of Node and Property.

  • Method Summary

    Modifier and Type
    Method
    Description
    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.
    String
    getName()
    Returns the name of this Item in qualified form.
    Node
    getParent()
    Returns the parent of this Item.
    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 Details

    • getPath

      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

      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: