Interface NodeService


  • @AlfrescoPublicApi
    public interface NodeService
    Interface for public and internal node and store operations.

    Amongst other things, this service must enforce the unique name check as mandated by the duplicate entity in the model.

        <type name="cm:folder">
           ...
           <associations>
              <child-association name="cm:contains">
                 ...
                 <duplicate>false</duplicate>
              </child-association>
           </associations>
        </type>
     
    When duplicates are not allowed, and the cm:name property of a node changes, then the org.alfresco.service.cmr.repository.DuplicateChildNodeNameException exception must be thrown. Client code can catch this exception and deal with it appropriately.
    Author:
    Derek Hulley
    • Method Detail

      • getStores

        @Auditable
        List<StoreRef> getStores()
        Gets a list of all available node store references
        Returns:
        Returns a list of store references
      • createStore

        @Auditable(parameters={"protocol","identifier"})
        StoreRef createStore​(String protocol,
                             String identifier)
                      throws StoreExistsException
        Create a new store for the given protocol and identifier. The implementation may create the store in any number of locations, including a database or Subversion.
        Parameters:
        protocol - implementation protocol
        identifier - the protocol-specific identifier
        Returns:
        Returns a reference to the store
        Throws:
        StoreExistsException
      • exists

        @Auditable(parameters="storeRef")
        boolean exists​(StoreRef storeRef)
        Parameters:
        storeRef - a reference to the store to look for
        Returns:
        Returns true if the store exists, otherwise false
      • exists

        @Auditable(parameters="nodeRef")
        boolean exists​(NodeRef nodeRef)
        Parameters:
        nodeRef - a reference to the node to look for
        Returns:
        Returns true if the node exists, otherwise false
      • getNodeStatus

        @Auditable(parameters="nodeRef")
        NodeRef.Status getNodeStatus​(NodeRef nodeRef)
        Gets the ID of the last transaction that caused the node to change. This includes deletions, so it is possible that the node being referenced no longer exists. If the node never existed, then null is returned.
        Parameters:
        nodeRef - a reference to a current or previously existing node
        Returns:
        Returns the status of the node, or null if the node never existed
      • getNodeRef

        @Auditable(parameters="nodeId")
        NodeRef getNodeRef​(Long nodeId)
        Get the node reference for a given node DB ID
        Parameters:
        nodeId - the node's DB ID
        Returns:
        the corresponding node reference or null if not found
      • getAllRootNodes

        @Auditable(parameters="storeRef")
        Set<NodeRef> getAllRootNodes​(StoreRef storeRef)
        Parameters:
        storeRef - a reference to an existing store
        Returns:
        Returns a set of references to all nodes in the store tagged with the root aspect
        Throws:
        InvalidStoreRefException - if the store could not be found
      • createNode

        @Auditable(parameters={"parentRef","assocTypeQName","assocQName","nodeTypeQName","properties"})
        ChildAssociationRef createNode​(NodeRef parentRef,
                                       QName assocTypeQName,
                                       QName assocQName,
                                       QName nodeTypeQName,
                                       Map<QName,​Serializable> properties)
                                throws InvalidNodeRefException,
                                       InvalidTypeException
        Creates a new, non-abstract, real node as a primary child of the given parent node.
        Parameters:
        parentRef - the parent node
        assocTypeQName - the type of the association to create. This is used for verification against the data dictionary.
        assocQName - the qualified name of the association
        nodeTypeQName - a reference to the node type
        properties - optional map of properties to keyed by their qualified names
        Returns:
        Returns a reference to the newly created child association
        Throws:
        InvalidNodeRefException - if the parent reference is invalid
        InvalidTypeException - if the node type reference is not recognised
        See Also:
        DictionaryService
      • moveNode

        @Auditable(parameters={"nodeToMoveRef","newParentRef","assocTypeQName","assocQName"})
        ChildAssociationRef moveNode​(NodeRef nodeToMoveRef,
                                     NodeRef newParentRef,
                                     QName assocTypeQName,
                                     QName assocQName)
                              throws InvalidNodeRefException
        Moves the primary location of the given node.

        This involves changing the node's primary parent and possibly the name of the association referencing it.

        If the new parent is in a different store from the original, then the entire node hierarchy is moved to the new store. Inter-store associations are not affected.

        Parameters:
        nodeToMoveRef - the node to move
        newParentRef - the new parent of the moved node
        assocTypeQName - the type of the association to create. This is used for verification against the data dictionary.
        assocQName - the qualified name of the new child association
        Returns:
        Returns a reference to the newly created child association
        Throws:
        InvalidNodeRefException - if either the parent node or move node reference is invalid
        org.alfresco.service.cmr.repository.CyclicChildRelationshipException - if the child partakes in a cyclic relationship after the add
        See Also:
        getPrimaryParent(NodeRef)
      • setType

        @Auditable(parameters={"nodeRef","typeQName"})
        void setType​(NodeRef nodeRef,
                     QName typeQName)
              throws InvalidNodeRefException
        Re-sets the type of the node. Can be called in order specialise a node to a sub-type. This should be used with caution since calling it changes the type of the node and thus implies a different set of aspects, properties and associations. It is the calling codes responsibility to ensure that the node is in a approriate state after changing the type.
        Parameters:
        nodeRef - the node reference
        typeQName - the type QName
        Throws:
        InvalidNodeRefException
        Since:
        1.1
      • deleteNode

        @Auditable(parameters="nodeRef")
        void deleteNode​(NodeRef nodeRef)
                 throws InvalidNodeRefException
        Deletes the given node.

        All associations (both children and regular node associations) will be deleted, and where the given node is the primary parent, the children will also be cascade deleted.

        Node stores may be mapped to an associated archive node store. For example, Alfresco ships with the mapping
        workspace://SpacesStore .. maps to .. archive://SpacesStore.
        When a node is deleted:

        • If there *is a mapping* from the node's current store to an archive store, the node is first copied to the archive store
        • If there *is no mapping* from the node's current store, then the node is permanently deleted
        When nodes have been archived, they contain all the details of the original location. Use the restore feature to return a node back to its original store.
        Parameters:
        nodeRef - reference to a node within a store
        Throws:
        InvalidNodeRefException - if the reference given is invalid
      • addChild

        @Auditable(parameters={"parentRef","childRef","assocTypeQName","qname"})
        ChildAssociationRef addChild​(NodeRef parentRef,
                                     NodeRef childRef,
                                     QName assocTypeQName,
                                     QName qname)
                              throws InvalidNodeRefException
        Makes a parent-child association between the given nodes. Both nodes must belong to the same store.
        Parameters:
        parentRef - the parent node
        childRef - the child node
        assocTypeQName - the qualified name of the association type as defined in the datadictionary
        qname - the qualified name of the association
        Returns:
        Returns a reference to the newly created child association
        Throws:
        InvalidNodeRefException - if the parent or child nodes could not be found
        org.alfresco.service.cmr.repository.CyclicChildRelationshipException - if the child partakes in a cyclic relationship after the add
      • addChild

        @Auditable(parameters={"parentRefs","childRef","assocTypeQName","qname"})
        List<ChildAssociationRef> addChild​(Collection<NodeRef> parentRefs,
                                           NodeRef childRef,
                                           QName assocTypeQName,
                                           QName qname)
                                    throws InvalidNodeRefException
        Associates a given child node with a given collection of parents. All nodes must belong to the same store.
        Parameters:
        parentRefs - the parent nodes (there will be this many associations created).
        childRef - the child node
        assocTypeQName - the qualified name of the association type as defined in the datadictionary
        qname - the qualified name of the association
        Returns:
        Returns a reference to the newly created child association
        Throws:
        InvalidNodeRefException - if the parent or child nodes could not be found
        org.alfresco.service.cmr.repository.CyclicChildRelationshipException - if the child partakes in a cyclic relationship after the add
      • removeChild

        @Auditable(parameters={"parentRef","childRef"})
        void removeChild​(NodeRef parentRef,
                         NodeRef childRef)
                  throws InvalidNodeRefException
        Severs all parent-child relationships between two nodes.

        The child node will be cascade deleted if one of the associations was the primary association, i.e. the one with which the child node was created.

        Parameters:
        parentRef - the parent end of the association
        childRef - the child end of the association
        Throws:
        InvalidNodeRefException - if the parent or child nodes could not be found
      • removeChildAssociation

        @Auditable(parameters="childAssocRef")
        boolean removeChildAssociation​(ChildAssociationRef childAssocRef)
        Remove a specific child association.

        The child node will be cascade deleted if the association was the primary association, i.e. the one with which the child node was created.

        Parameters:
        childAssocRef - the association to remove
        Returns:
        Returns true if the association existed, otherwise false.
      • removeSecondaryChildAssociation

        @Auditable(parameters="childAssocRef")
        boolean removeSecondaryChildAssociation​(ChildAssociationRef childAssocRef)
        Remove a specific secondary child association.
        Parameters:
        childAssocRef - the association to remove
        Returns:
        Returns true if the association existed, otherwise false.
        Throws:
        IllegalArgumentException - if the association is primary
        Since:
        4.0
      • setProperties

        @Auditable(parameters={"nodeRef","properties"})
        void setProperties​(NodeRef nodeRef,
                           Map<QName,​Serializable> properties)
                    throws InvalidNodeRefException
        Replace all current properties on the node with the given properties. The properties given must still fulfill the requirements of the class and aspects relevant to the node.

        NOTE: Null values are allowed.

        Parameters:
        nodeRef - the node to chance
        properties - all the properties of the node keyed by their qualified names
        Throws:
        InvalidNodeRefException - if the node could not be found
      • setProperty

        @Auditable(parameters={"nodeRef","qname","value"})
        void setProperty​(NodeRef nodeRef,
                         QName qname,
                         Serializable value)
                  throws InvalidNodeRefException
        Sets the value of a property to be any Serializable instance.

        NOTE: Null values are allowed.

        Parameters:
        nodeRef - a reference to an existing node
        qname - the fully qualified name of the property
        value - the value of the property - never null
        Throws:
        InvalidNodeRefException - if the node could not be found
      • getChildAssocs

        @Auditable(parameters={"nodeRef","typeQNamePattern","qnamePattern","maxResults","preload"})
        List<ChildAssociationRef> getChildAssocs​(NodeRef nodeRef,
                                                 QNamePattern typeQNamePattern,
                                                 QNamePattern qnamePattern,
                                                 int maxResults,
                                                 boolean preload)
                                          throws InvalidNodeRefException
        Gets all child associations where the pattern of the association qualified name is an exact match.
        Parameters:
        nodeRef - the parent node - usually a container
        typeQNamePattern - the qualified name of the association (null to ignore)
        qnamePattern - the path qualified name (null to ignore)
        maxResults - the number of results to get
        preload - true if the nodes must be preloaded into the cache
        Returns:
        Returns a list of ChildAssociationRef instances
        Throws:
        InvalidNodeRefException - if the node could not be found
        See Also:
        QName
      • getChildAssocs

        @Auditable(parameters={"nodeRef","childNodeTypes"})
        List<ChildAssociationRef> getChildAssocs​(NodeRef nodeRef,
                                                 Set<QName> childNodeTypeQNames)
        Retrieve immediate children of a given node where the child nodes are in the given inclusive list.
        Parameters:
        nodeRef - the parent node - usually a container
        childNodeTypeQNames - the types that the children may be. Subtypes are not automatically calculated and the list must therefore be exhaustive.
        Returns:
        Returns a list of ChildAssociationRef instances.
        Throws:
        InvalidNodeRefException - if the node could not be found
      • getChildAssocsByPropertyValue

        @Auditable(parameters={"nodeRef","propertyQName","value"})
        List<ChildAssociationRef> getChildAssocsByPropertyValue​(NodeRef nodeRef,
                                                                QName propertyQName,
                                                                Serializable value)
        Retrieve the immediate children of a given node based on the value of a property of those children.

        If the property to be searched is multi-valued then will match on any one values.

        Please note, the following system maintained properties that cannot be used with this method.

        • cm:name - use getChildByName instead
        • cm:created
        • cm:creator
        • cm:modified
        • cm:modifier
        • sys:node-uuid
        • sys:node-dbid
        • sys:store-identifier
        • sys:store-protocol
        Parameters:
        nodeRef - the parent node - usually a container
        propertyQName - the fully qualified name of the property
        value - the value to search for. Must be a simple type such as String, Number, Date or Boolean, it cannot be a collection, a content property, MLText or a float.
        Returns:
        Returns a list of ChildAssociationRef instances.
      • getChildByName

        @Auditable(parameters={"nodeRef","assocTypeQName","childName"})
        NodeRef getChildByName​(NodeRef nodeRef,
                               QName assocTypeQName,
                               String childName)
        Get the node with the given name within the context of the parent node. The name is case-insensitive as Alfresco has to support case-insensitive clients as standard.

        That API method getChildByName only works for associations that don't allow duplicate child names. See cm:folder and the duplicate tag. Child associations without this allow duplicate child names and therefore it is possible to have multiple children with the same name stored against the given association type.

        Parameters:
        nodeRef - the parent node - usuall a container
        assocTypeQName - the type of the association
        childName - the name of the node as per the property cm:name
        Returns:
        Returns the child node or null if not found
      • getChildAssocsWithoutParentAssocsOfType

        @Auditable(parameters={"parent","assocTypeQName"})
        Collection<ChildAssociationRef> getChildAssocsWithoutParentAssocsOfType​(NodeRef parent,
                                                                                QName assocTypeQName)
        Gets the set of child associations of a certain parent node without parent associations of a certain type to other nodes with the same parent! In effect the 'orphans' with respect to a certain association type.
        Parameters:
        parent - the parent node reference
        assocTypeQName - the association type QName
        Returns:
        a set of child associations
      • removeAssociation

        @Auditable(parameters={"sourceRef","targetRef","assocTypeQName"})
        void removeAssociation​(NodeRef sourceRef,
                               NodeRef targetRef,
                               QName assocTypeQName)
                        throws InvalidNodeRefException
        Parameters:
        sourceRef - the associaton source node
        targetRef - the association target node
        assocTypeQName - the qualified name of the association type
        Throws:
        InvalidNodeRefException - if either of the nodes could not be found
      • setAssociations

        @Auditable(parameters={"sourceRef","assocTypeQName","targetRefs"})
        void setAssociations​(NodeRef sourceRef,
                             QName assocTypeQName,
                             List<NodeRef> targetRefs)
        Re-assign all typed target associations for a given node.
        Parameters:
        sourceRef - the source node
        assocTypeQName - the specific type of the association
        targetRefs - the target nodes (not null but empty list is accepted).
      • getAssoc

        AssociationRef getAssoc​(Long id)
        Gets an association by ID.
        Parameters:
        id - the association id
        Returns:
        the association, or null if it does not exist
      • getTargetAssocs

        @Auditable(parameters={"sourceRef","qnamePattern"})
        List<AssociationRef> getTargetAssocs​(NodeRef sourceRef,
                                             QNamePattern qnamePattern)
                                      throws InvalidNodeRefException
        Fetches all associations from the given source where the associations' qualified names match the pattern provided.

        The results are ordered if a specific type of association is requested

        Parameters:
        sourceRef - the association source
        qnamePattern - the association qname pattern to match against
        Returns:
        a list of NodeAssocRef instances for which the given node is a source
        Throws:
        InvalidNodeRefException - if the source node could not be found
        See Also:
        QName, RegexQNamePattern.MATCH_ALL
      • getTargetAssocsByPropertyValue

        @Auditable(parameters={"sourceRef","qnamePattern","propertyQName","propertyValue"})
        List<AssociationRef> getTargetAssocsByPropertyValue​(NodeRef sourceRef,
                                                            QNamePattern qnamePattern,
                                                            QName propertyQName,
                                                            Serializable propertyValue)
        Fetches all associations from the given source where the associations' qualified names match the pattern provided.

        The results are ordered if a specific type of association is requested

        Parameters:
        sourceRef - the association source
        qnamePattern - the association qname pattern to match against
        propertyQName - the fully qualified name of the property of the association target. Optional parameter - can be null.
        propertyValue - association target property value to search for. Must be a simple type such as String, Number, Date or Boolean, it cannot be a collection, a content property, MLText or a float. If propertyQName is null the value is ignored.
        Returns:
        a list of AssociationRef instances for which the given node is a source
        Throws:
        InvalidNodeRefException - if the source node could not be
        IllegalArgumentException - if propertyQName is a system maintained property
        See Also:
        QName, RegexQNamePattern.MATCH_ALL
      • getPaths

        @Auditable(parameters={"nodeRef","primaryOnly"})
        List<Path> getPaths​(NodeRef nodeRef,
                            boolean primaryOnly)
                     throws InvalidNodeRefException
        The root node has an entry in the path(s) returned. For this reason, there will always be at least one path element in the returned path(s). The first element will have a null parent reference and qname.
        Parameters:
        nodeRef - NodeRef
        primaryOnly - true if only the primary path must be retrieved. If true, the result will have exactly one entry.
        Returns:
        Returns a List of all possible paths to the given node
        Throws:
        InvalidNodeRefException - if the node could not be found
      • getStoreArchiveNode

        @Auditable(parameters="storeRef")
        NodeRef getStoreArchiveNode​(StoreRef storeRef)
        Get the node where archived items will have gone when deleted from the given store.
        Parameters:
        storeRef - the store that items were deleted from
        Returns:
        Returns the archive node parent
      • restoreNode

        @Auditable(parameters={"archivedNodeRef","destinationParentNodeRef","assocTypeQName","assocQName"})
        NodeRef restoreNode​(NodeRef archivedNodeRef,
                            NodeRef destinationParentNodeRef,
                            QName assocTypeQName,
                            QName assocQName)
        Restore an individual node (along with its sub-tree nodes) to the target location. The archived node must have the archived aspect set against it. This would have been applied when a node was originally deleted.
        Parameters:
        archivedNodeRef - the archived node
        destinationParentNodeRef - the parent to move the node into or null to use the original
        assocTypeQName - the primary association type name to use in the new location or null to use the original
        assocQName - the primary association name to use in the new location or null to use the original
        Returns:
        Returns the reference to the newly created node
      • countChildAssocs

        @Auditable(parameters={"nodeRef","isPrimary"})
        int countChildAssocs​(NodeRef nodeRef,
                             boolean isPrimary)
                      throws InvalidNodeRefException
        Counts the number of child associations of nodeRef.
        Parameters:
        nodeRef - the parent node id
        isPrimary - count just primary associations?
        Returns:
        Returns the number of child associations
        Throws:
        InvalidNodeRefException