Package javax.jcr

Interface Item

    • Method Summary

      All Methods Instance Methods Abstract Methods Deprecated Methods 
      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.
      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.

      • 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)