Package org.nuxeo.ecm.core.api

Interface CoreSession

All Known Subinterfaces:
CloseableCoreSession
All Known Implementing Classes:
AbstractSession, LocalSession
public interface CoreSession
A session to the Nuxeo Core.
Author:
Bogdan Stefanescu, Florent Guillaume
See Also:

  • Field Details

  • Method Details

    • close

      @Deprecated void close()
      Deprecated.
      since 10.1
      Does nothing.
      Since:
      5.9.3

    • getDocumentType

      DocumentType getDocumentType(String type)
      Gets the document type object given its type name.
      Parameters:
      type - the document type name
      Returns:
      the type the doc type object

    • cancel

      void cancel()
      Cancels any pending change made through this session.

    • save

      void save()
      Saves any pending changes done until now through this session.

    • getSessionId

      @Deprecated String getSessionId()
      Deprecated.
      since 11.1
      Returns the repository name and principal.
      Returns:
      the repository name and principal

    • getPrincipal

      NuxeoPrincipal getPrincipal()
      Gets the principal that created the client session.
      Returns:
      the principal

    • hasPermission

      boolean hasPermission(DocumentRef docRef, String permission)
      Checks if the principal that created the client session has the given privilege on the referred document.

    • hasPermission

      boolean hasPermission(NuxeoPrincipal principal, DocumentRef docRef, String permission)
      Checks if a given principal has the given privilege on the referred document.

    • filterGrantedPermissions

      Collection<String> filterGrantedPermissions(NuxeoPrincipal principal, DocumentRef docRef, Collection<String> permissions)
      Filters the supplied permissions based on whether they are granted to a given principal for a given document.
      Since:
      9.1

    • getRootDocument

      DocumentModel getRootDocument()
      Gets the root document of this repository.
      Returns:
      the root document. cannot be null

    • getDocument

      DocumentModel getDocument(DocumentRef docRef) throws DocumentNotFoundException
      Gets a document model given its reference.

      The default schemas are used to populate the returned document model. Default schemas are configured via the document type manager.

      Any other data model not part of the default schemas will be lazily loaded as needed.

      Parameters:
      docRef - the document reference
      Returns:
      the document
      Throws:
      DocumentNotFoundException - if the document cannot be found

    • getDocuments

      DocumentModelList getDocuments(DocumentRef[] docRefs) throws DocumentNotFoundException
      Gets a list of documents given their references.

      Documents that are not accessible are skipped.

      Throws:
      DocumentNotFoundException - if a document cannot be found

    • getChild

      DocumentModel getChild(DocumentRef parent, String name)
      Gets a child document given its name and the parent reference.

      Throws an exception if the document could not be found.

      If the supplied id is null, returns the default child of the document if any, otherwise raises an exception.

      If the parent is null or its path is null, then root is considered.

      Parameters:
      parent - the reference to the parent document
      name - the name of the child document to retrieve
      Returns:
      the named child if exists
      Throws:
      DocumentNotFoundException - if there is no child with the given name

    • hasChild

      boolean hasChild(DocumentRef parent, String name)
      Tests if the document has a child with the given name.

      This operation silently ignores non-folder documents: If the document is not a folder then returns false.

      Parameters:
      parent - the document
      name - the child name
      Returns:
      true if the document has a child with the given name
      Since:
      7.3

    • getChildren

      DocumentModelList getChildren(DocumentRef parent)
      Gets the children of the given parent.
      Parameters:
      parent - the parent reference
      Returns:
      the children if any, an empty list if no children or null if the specified parent document is not a folder

    • getChildrenIterator

      DocumentModelIterator getChildrenIterator(DocumentRef parent)
      Gets an iterator to the children of the given parent.
      Parameters:
      parent - the parent reference
      Returns:
      iterator over the children collection or null if the specified parent document is not a folder

    • getChildren

      DocumentModelList getChildren(DocumentRef parent, String type)
      Gets the children of the given parent filtered according to the given document type.
      Parameters:
      parent - the parent reference
      type - the wanted document type
      Returns:
      the documents if any, an empty list if none were found or null if the parent document is not a folder

    • getChildrenIterator

      DocumentModelIterator getChildrenIterator(DocumentRef parent, String type)
      Gets an iterator to the children of the given parent filtered according to the given document type.

    • getChildren

      DocumentModelList getChildren(DocumentRef parent, String type, String perm)
      Gets the children of the given parent filtered according to the given document type and permission.
      Parameters:
      parent - the parent reference
      type - the wanted document type
      perm - the permission the user must have
      Returns:
      the documents if any, an empty list if none were found or null if the parent document is not a folder

    • getChildren

      DocumentModelList getChildren(DocumentRef parent, String type, String perm, Filter filter, Sorter sorter)
      Same as getChildren(DocumentRef, String, String) but the result is filtered and then sorted using the specified filter and sorter.
      Parameters:
      parent - the parent reference
      type - the wanted type
      perm - permission to check for. If null, defaults to READ
      filter - the filter to use if any, null otherwise
      sorter - the sorter to use if any, null otherwise
      Returns:
      the list of the children or an empty list if no children were found or null if the given parent is not a folder

    • getChildrenRefs

      List<DocumentRef> getChildrenRefs(DocumentRef parentRef, String perm)
      Gets the references of the children. No permission is checked if perm is null.
      Parameters:
      parentRef - the parent reference
      perm - the permission to check on the children (usually READ); if null, no permission is checked
      Returns:
      a list of children references
      Since:
      1.4.1

    • getChildrenIterator

      DocumentModelIterator getChildrenIterator(DocumentRef parent, String type, String perm, Filter filter)
      Gets the children of the given parent filtered according to the given document type and permission. Long result sets are loaded frame by frame transparently by the DocumentModelIterator.

    • getChildren

      DocumentModelList getChildren(DocumentRef parent, String type, Filter filter, Sorter sorter)
      Same as getChildren(DocumentRef, String, String, Filter, Sorter) without specific permission filtering.
      Parameters:
      parent - the parent reference
      type - the wanted type
      filter - the filter to use if any, null otherwise
      sorter - the sorter to use if any, null otherwise
      Returns:
      the list of the children or an empty list if no children were found or null if the given parent is not a folder

    • getFolders

      DocumentModelList getFolders(DocumentRef parent)
      Same as getChildren(DocumentRef) but returns only folder documents.
      Parameters:
      parent - the parent ref
      Returns:
      a list of children if any, an empty one if none or null if the given parent is not a folder

    • getFolders

      DocumentModelList getFolders(DocumentRef parent, Filter filter, Sorter sorter)
      Same as getFolders(DocumentRef) but uses an optional filter and sorter on the result.
      Parameters:
      parent - the parent reference
      filter - the filter to use or null if none
      sorter - the sorter to use or null if none
      Returns:
      a list of children if any, an empty one if none or null if the given parent is not a folder

    • getFiles

      DocumentModelList getFiles(DocumentRef parent)
      Same as getChildren(DocumentRef) but returns only non-folder documents.
      Parameters:
      parent - the parent reference
      Returns:
      a list of children if any, an empty one if none or null if the given parent is not a folder

    • getFiles

      DocumentModelList getFiles(DocumentRef parent, Filter filter, Sorter sorter)
      Same as getFiles(org.nuxeo.ecm.core.api.DocumentRef) but uses an optional filter and sorter on the result.
      Parameters:
      parent - the parent reference
      filter - the filter to use or null if none
      sorter - the sorter to use or null if none
      Returns:
      a list of children if any, an empty one if none or null if the given parent is not a folder

    • getParentDocumentRef

      DocumentRef getParentDocumentRef(DocumentRef docRef)
      Returns the parent ref of the document referenced by docRef or null if this is the root document.

      This method does not check the permissions on the parent document of this CoreSession's Principal .

      Since:
      5.4.2

    • getParentDocument

      DocumentModel getParentDocument(DocumentRef docRef)
      Gets the parent document or null if this is the root document.
      Returns:
      the parent document or null if this is the root document

    • getParentDocuments

      List<DocumentModel> getParentDocuments(DocumentRef docRef)
      Gets the parent documents in path from the root to the given document or empty list if this is the root document.

      Documents the principal is is not allowed to browse are filtered out the parents list.

      Returns:
      the list with parent documents or empty list if this is the root document

    • exists

      boolean exists(DocumentRef docRef)
      Tests if the document pointed by the given reference exists and is accessible.

      This operation makes no difference between non-existence and permission problems.

      If the parent is null or its path is null, then root is considered.

      Parameters:
      docRef - the reference to the document to test for existence
      Returns:
      true if the referenced document exists, false otherwise

    • hasChildren

      boolean hasChildren(DocumentRef docRef)
      Tests if the document has any children.

      This operation silently ignores non-folder documents: If the document is not a folder then returns false.

      If the parent is null or its path is null, then root is considered.

      Parameters:
      docRef - the reference to the document to test
      Returns:
      true if document has children, false otherwise

    • createDocumentModel

      DocumentModel createDocumentModel(String typeName)
      Creates a document model using type name.

      Used to fetch initial datamodels from the type definition.

      DocumentModel creation notifies a DocumentEventTypes.EMPTY_DOCUMENTMODEL_CREATED so that core event listener can initialize its content with computed properties.

      Returns:
      the initial document model

    • createDocumentModel

      DocumentModel createDocumentModel(String parentPath, String name, String typeName)
      Creates a document model using required information.

      Used to fetch initial datamodels from the type definition.

      DocumentModel creation notifies a DocumentEventTypes.EMPTY_DOCUMENTMODEL_CREATED so that core event listener can initialize its content with computed properties.

      Parameters:
      parentPath - the parent path
      name - The destination name
      typeName - the type name
      Returns:
      the initial document model

    • newDocumentModel

      DocumentModel newDocumentModel(DocumentRef parentRef, String name, String typeName)
      Creates a new document model using required information.

      Used to fetch initial datamodels from the type definition.

      DocumentModel creation notifies a DocumentEventTypes.EMPTY_DOCUMENTMODEL_CREATED so that core event listener can initialize its content with computed properties.

      Parameters:
      parentRef - the parent document ref DocumentRef
      name - The destination name
      typeName - the type name
      Returns:
      the initial document model
      Since:
      11.1

    • createDocumentModel

      DocumentModel createDocumentModel(String typeName, Map<String,Object> options)
      Creates a document model using required information.

      Used to fetch initial datamodels from the type definition.

      DocumentModel creation notifies a DocumentEventTypes.EMPTY_DOCUMENTMODEL_CREATED so that core event listener can initialize its content with computed properties.

      Parameters:
      typeName - the type name
      options - additional contextual data provided to core event listeners
      Returns:
      the initial document model

    • createDocument

      DocumentModel createDocument(DocumentModel model)
      Creates a document using given document model for initialization.

      The model contains path of the new document, its type and optionally the initial data models of the document.

      Parameters:
      model - the document model to use for initialization
      Returns:
      the created document

    • createDocument

      DocumentModel[] createDocument(DocumentModel[] docModels)
      Bulk creation of documents.
      Parameters:
      docModels - the document models to use for intialization
      Returns:
      the created documents

    • importDocuments

      void importDocuments(List<DocumentModel> docModels)
      Low-level import of documents, reserved for the administrator.

      This method is used to import documents with given ids, or directly import versions and proxies.

      The id, parent, name and typeName must be present in each docModel.

      The context data needs to be filled with values depending on the type of the document:

      For a proxy (type = "ecm:proxyType"): IMPORT_PROXY_TARGET_ID and IMPORT_PROXY_VERSIONABLE_ID.

      For a version (no parent): IMPORT_VERSION_VERSIONABLE_ID, IMPORT_VERSION_CREATED, IMPORT_VERSION_LABEL and IMPORT_VERSION_DESCRIPTION.

      For a live document: IMPORT_BASE_VERSION_ID and IMPORT_CHECKED_IN (Boolean).

      For a live document or a version: IMPORT_LIFECYCLE_POLICY , IMPORT_LIFECYCLE_STATE, IMPORT_VERSION_MAJOR (Long) and IMPORT_VERSION_MINOR (Long).

      Parameters:
      docModels - the documents to create

    • saveDocument

      DocumentModel saveDocument(DocumentModel docModel)
      Saves changes done on the given document model.
      Parameters:
      docModel - the document model that needs modified

    • saveDocuments

      void saveDocuments(DocumentModel[] docModels)
      Bulk document saving.
      Parameters:
      docModels - the document models that needs to be saved

    • canRemoveDocument

      boolean canRemoveDocument(DocumentRef docRef)
      Check if a document can be removed. This needs the SecurityConstants.REMOVE permission on the document and the SecurityConstants.REMOVE_CHILDREN permission on the parent.

      For an archived version to be removeable, it must not be referenced from any proxy or be the base of a working document, and the REMOVE permission must be available on the working document (or the user must be an administrator if no working document exists).

      If the SecurityConstants.REMOVE permissions is blocked on a descendant of the document for the current principal, then the document cannot be removed.

      If a descendant of the document is retained or under legal hold, then the document cannot be removed.

      Parameters:
      docRef - the document
      Returns:
      true if the document can be removed

    • removeDocument

      void removeDocument(DocumentRef docRef)
      Removes this document and all its children, if any.
      Parameters:
      docRef - the reference to the document to remove

    • removeDocuments

      void removeDocuments(DocumentRef[] docRefs)
      Bulk method to remove documents.

      This method is safe with respect to orderings: it doesn't fail if an ancestor of a document occurs before the document.

      Parameters:
      docRefs - the refs to the document to remove

    • removeChildren

      void removeChildren(DocumentRef docRef)
      Removes all children from the given document.
      Parameters:
      docRef - the reference to the document to remove

    • copy

      DocumentModel copy(DocumentRef src, DocumentRef dst, String name, CoreSession.CopyOption... copyOptions)
      Copies the source document to the destination folder under the given name. If the name is null the original name is preserved.

      If the destination document is not a folder or it doesn't exists then throws an exception.

      If the source is a proxy the destination will be a copy of the proxy.

      Parameters:
      src - the source document reference
      dst - the destination folder reference
      name - the new name of the file or null if the original name must be preserved
      copyOptions - the options for copy

    • copy

      List<DocumentModel> copy(List<DocumentRef> src, DocumentRef dst, CoreSession.CopyOption... copyOptions)
      Bulk copy. Destination must be a folder document.
      Parameters:
      src - the documents to copy
      dst - the destination folder
      copyOptions - the options for copy
      Since:
      8.2

    • copyProxyAsDocument

      DocumentModel copyProxyAsDocument(DocumentRef src, DocumentRef dst, String name, CoreSession.CopyOption... copyOptions)
      Work like copy but in the case of a source proxy the destination will be a new document instead of a proxy.
      Parameters:
      src - the source document reference
      dst - the destination folder reference
      name - the new name of the file or null if the original name must be preserved
      copyOptions - the options for copy
      Since:
      8.2
      See Also:

    • copyProxyAsDocument

      List<DocumentModel> copyProxyAsDocument(List<DocumentRef> src, DocumentRef dst, CoreSession.CopyOption... copyOptions)
      Bulk copyProxyAsDocument. Destination must be a folder document.
      Parameters:
      src - the documents to copy
      dst - the destination folder
      copyOptions - the options of copy
      Since:
      8.2

    • move

      DocumentModel move(DocumentRef src, DocumentRef dst, String name)
      Moves the source document to the destination folder under the given name. If the name is null or if there is a collision, a suitable new name is found.
      Parameters:
      src - the source document reference
      dst - the destination folder reference
      name - the new name of the file, or null

    • move

      void move(List<DocumentRef> src, DocumentRef dst)
      Bulk move. Destination must be a folder document.
      Parameters:
      src - the documents to move
      dst - the destination folder

    • getACP

      ACP getACP(DocumentRef docRef)
      Gets the document access control policy.

      The returned ACP is the ACP defined on that document if any + the inherited ACL if any. If neither a local ACP nor inherited ACL exists null is returned.

      Note that modifying the returned ACP will not affect in any way the stored document ACP. To modify the ACP you must explicitely set it by calling setACP(DocumentRef, ACP, boolean)

      This method will always fetch a fresh ACP from the storage. The recommended way to get the ACP is to use DocumentModel.getACP() this way the ACP will be cached at the document model level and so you can use it for multiple permission checks without fetching it each time.

      Parameters:
      docRef - the doc ref to retrieve ACP or null if none
      Returns:
      the ACP

    • setACP

      void setACP(DocumentRef docRef, ACP acp, boolean overwrite)
      Sets the ACP for this document.

      If the ACP contains an INHERITED ACL it will be discarded. Only ACLs relative to the current document may be changed.

      If the overwrite argument is false, the ACP is merged with the existing one if any. The merge is done as follow:

      • If any ACL is that already exists on the document ACp is redefined by the new ACO then it will be replaced by the new one. So if you want to remove an ACl in this mode you need to specify an empty ACL.
      • If the new ACP contains an ACl that is not defined by the old one the it will be added to the merged ACP.
      • If the owners are specified then they will replace the existing ones if any. Otherwise the old owners are preserved if any. As for the ACL if you want to remove existing owners you need to specify an empty owner array (and not a null one)
      If the overwrite argument is true, the old ACP will be replaced by the new one.

      This way if you can remove the existing ACP by specifying a null ACP and overwrite argument set to true.

      Setting a null ACP when overwrite is false will do nothing.

    • replaceACE

      void replaceACE(DocumentRef docRef, String aclName, ACE oldACE, ACE newACE)
      Replace the oldACE with the newACE on the given aclName.

      Since:
      7.4

    • updateReadACLs

      void updateReadACLs(Collection<String> docIds)
      Updates the Read ACLs for some documents.

      For INTERNAL use by the core.

      Parameters:
      docIds - the document ids
      Since:
      9.10

    • isNegativeAclAllowed

      boolean isNegativeAclAllowed()
      Returns true if negative ACLs are allowed.

      Negative ACLs are ACLs that include an ACE with a deny (isGranted=false). This does not include the full-blocking ACE for Everyone/Everything, which is always allowed.

      Returns:
      true if negative ACLs are allowed
      Since:
      6.0

    • getDataModel

      DataModel getDataModel(DocumentRef docRef, Schema schema)
      Retrieves a data model given a document reference and a schema.

      For INTERNAL use by the core.

      Since:
      5.4.2

    • getLastDocumentVersion

      DocumentModel getLastDocumentVersion(DocumentRef docRef)
      Gets the document corresponding to the last version for the given document.
      Parameters:
      docRef - the reference to the document
      Returns:
      the document model corresponding to the version

    • getLastDocumentVersionRef

      DocumentRef getLastDocumentVersionRef(DocumentRef docRef)
      Gets the document reference corresponding to the last version for the given document.
      Parameters:
      docRef - the reference to the document
      Returns:
      the document reference corresponding to the last version

    • getSourceDocument

      DocumentModel getSourceDocument(DocumentRef docRef)
      Gets the head (live) document for this document.
      Parameters:
      docRef - the reference to the document
      Returns:
      the version

    • getVersionsRefs

      List<DocumentRef> getVersionsRefs(DocumentRef docRef)
      Gets the references of the versions of the document.
      Parameters:
      docRef - the reference to the document
      Returns:
      a list of version references
      Since:
      1.4.1

    • getVersions

      List<DocumentModel> getVersions(DocumentRef docRef)
      Retrieves all the versions for a specified document.
      Parameters:
      docRef - the reference to the document
      Returns:
      the list of DocumentModel representing versions, empty list if none is found.

    • getVersionsForDocument

      List<VersionModel> getVersionsForDocument(DocumentRef docRef)
      Retrieves all the versions for a specified document.
      Parameters:
      docRef - the reference to the document
      Returns:
      the list of VersionModel representing versions, empty list if none is found.

    • getVersion

      DocumentModel getVersion(String versionableId, VersionModel versionModel)
      Gets a document version, given the versionable id and label.

      The version model contains the label of the version to look for. On return, it is filled with the version's description and creation date.

      Parameters:
      versionableId - the versionable id
      versionModel - the version model holding the label
      Returns:
      the version, or null if not found

    • getVersionLabel

      String getVersionLabel(DocumentModel docModel)
      Gets the version label for a document, according to the versioning service.
      Parameters:
      docModel - the document
      Returns:
      the version label

    • getDocumentWithVersion

      DocumentModel getDocumentWithVersion(DocumentRef docRef, VersionModel version)
      Returns a document that represents the specified version of the document.
      Parameters:
      docRef - the reference to the document
      version - the version for which we want the corresponding document

    • restoreToVersion

      DocumentModel restoreToVersion(DocumentRef docRef, DocumentRef versionRef, boolean skipSnapshotCreation, boolean skipCheckout)
      Restores the given document to the specified version.
      Parameters:
      docRef - the reference to the document
      versionRef - the reference to the version
      skipSnapshotCreation - true if the document should not be snapshotted before being restored
      skipCheckout - true if the restored document should be kept in a checked-in state
      Since:
      5.4

    • restoreToVersion

      DocumentModel restoreToVersion(DocumentRef docRef, DocumentRef versionRef)
      Restores the given document to the specified version.
      Parameters:
      docRef - the reference to the document
      versionRef - the reference to the version
      Since:
      5.4

    • getBaseVersion

      DocumentRef getBaseVersion(DocumentRef docRef)
      Gets the version to which a checked in document is linked.

      Returns null for a checked out document or a version or a proxy.

      Returns:
      the version, or null

    • checkOut

      void checkOut(DocumentRef docRef)
      Checks out a versioned document.
      Parameters:
      docRef - the reference to the document

    • checkIn

      DocumentRef checkIn(DocumentRef docRef, VersioningOption option, String checkinComment)
      Checks in a modified document, creating a new version.
      Parameters:
      docRef - the reference to the document
      option - whether to do create a new VersioningOption.MINOR or VersioningOption.MAJOR version during check in
      checkinComment - the checkin comment
      Returns:
      the version just created
      Since:
      5.4

    • isCheckedOut

      boolean isCheckedOut(DocumentRef docRef)
      Returns whether the current document is checked-out or not.
      Parameters:
      docRef - the reference to the document

    • getVersionSeriesId

      String getVersionSeriesId(DocumentRef docRef)
      Gets the version series id for a document.

      All documents and versions derived by a check in or checkout from the same original document share the same version series id.

      Parameters:
      docRef - the document reference
      Returns:
      the version series id
      Since:
      5.4

    • getWorkingCopy

      DocumentModel getWorkingCopy(DocumentRef docRef)
      Gets the working copy (live document) for a proxy or a version.
      Parameters:
      docRef - the document reference
      Returns:
      the working copy, or null if not found
      Since:
      5.4

    • removeOrphanVersions

      List<DocumentRef> removeOrphanVersions(DocumentRef docRef)
      Removes orphan versions when the live document doesn't exist and there is no proxy pointing to this document. A version stays referenced, and therefore is not removed, if any proxy points to a version in the version history of any live document, or in the case of tree snapshot if there is a snapshot containing a version in the version history of any live document.
      Parameters:
      docRef - of the live document
      Returns:
      the list of orphan version deleted.
      Since:
      2021.44

    • createProxy

      DocumentModel createProxy(DocumentRef docRef, DocumentRef folderRef)
      Creates a generic proxy to the given document inside the given folder.

      The document may be a version, or a working copy (live document) in which case the proxy will be a "shortcut".

      Since:
      1.6.1 (5.3.1)

    • query

      DocumentModelList query(String query)
      Executes the given NXQL query an returns the result.
      Parameters:
      query - the query to execute
      Returns:
      the query result

    • query

      DocumentModelList query(String query, int max)
      Executes the given NXQL query an returns the result.
      Parameters:
      query - the query to execute
      max - number of document to retrieve
      Returns:
      the query result

    • query

      DocumentModelList query(String query, Filter filter)
      Executes the given NXQL query and returns the result that matches the filter.
      Parameters:
      query - the query to execute
      filter - the filter to apply to result
      Returns:
      the query result

    • query

      DocumentModelList query(String query, Filter filter, int max)
      Executes the given NXQL query and returns the result that matches the filter.
      Parameters:
      query - the query to execute
      filter - the filter to apply to result
      max - number of document to retrieve
      Returns:
      the query result

    • query

      DocumentModelList query(String query, Filter filter, long limit, long offset, boolean countTotal)
      Executes the given NXQL query and returns the result that matches the filter.
      Parameters:
      query - the query to execute
      filter - the filter to apply to result
      limit - the maximum number of documents to retrieve, or 0 for all of them
      offset - the offset (starting at 0) into the list of documents
      countTotal - if true, return a DocumentModelList that includes a total size of the underlying list (size if there was no limit or offset)
      Returns:
      the query result

    • query

      DocumentModelList query(String query, Filter filter, long limit, long offset, long countUpTo)
      Executes the given NXQL query and returns the result that matches the filter.
      Parameters:
      query - the query to execute
      filter - the filter to apply to result
      limit - the maximum number of documents to retrieve, or 0 for all of them
      offset - the offset (starting at 0) into the list of documents
      countUpTo - if -1, count the total size without offset/limit.
      If 0, don't count the total size.
      If n, count the total number if there are less than n documents otherwise set the size to -1.
      Returns:
      the query result
      Since:
      5.6

    • query

      DocumentModelList query(String query, String queryType, Filter filter, long limit, long offset, boolean countTotal)
      Executes the given query and returns the result that matches the filter.
      Parameters:
      query - the query to execute
      queryType - the query type, like "NXQL"
      filter - the filter to apply to result
      limit - the maximum number of documents to retrieve, or 0 for all of them
      offset - the offset (starting at 0) into the list of documents
      countTotal - if true, return a DocumentModelList that includes a total size of the underlying list (size if there was no limit or offset)
      Returns:
      the query result
      Since:
      5.5

    • query

      DocumentModelList query(String query, String queryType, Filter filter, long limit, long offset, long countUpTo)
      Executes the given query and returns the result that matches the filter.
      Parameters:
      query - the query to execute
      queryType - the query type, like "NXQL"
      filter - the filter to apply to result
      limit - the maximum number of documents to retrieve, or 0 for all of them
      offset - the offset (starting at 0) into the list of documents
      countUpTo - if -1, return a DocumentModelList that includes a total size of the underlying list (size if there was no limit or offset).
      If 0, don't return the total size of the underlying list.
      If n, return the total size of the underlying list when the size is smaller than n else return a total size of -1.
      Returns:
      the query result
      Since:
      5.6

    • queryAndFetch

      IterableQueryResult queryAndFetch(String query, String queryType, Object... params)
      Executes the given query and returns an iterable of maps containing the requested properties (which must be closed when done).
      Parameters:
      query - the query to execute
      queryType - the query type, usually "NXQL"
      params - optional query-type-dependent parameters
      Returns:
      an IterableQueryResult, which must be closed after use

    • queryAndFetch

      IterableQueryResult queryAndFetch(String query, String queryType, boolean distinctDocuments, Object... params)
      Executes the given query and returns an iterable of maps containing the requested properties (which must be closed when done).

      It's possible to specify distinctDocuments = true to get a maximum of one row of results per document, this will behave differently only when the WHERE clause contains wildcards.

      Parameters:
      query - the query to execute
      queryType - the query type, usually "NXQL"
      distinctDocuments - if true then a maximum of one row per document will be returned
      params - optional query-type-dependent parameters
      Returns:
      an IterableQueryResult, which must be closed after use
      Since:
      7.10-HF04, 8.2

    • queryProjection

      PartialList<Map<String,Serializable>> queryProjection(String query, long limit, long offset)
      Executes the given NXQL query and returns the result that matches the filter.
      Parameters:
      query - the query to execute
      limit - the maximum number of documents to retrieve, or 0 for all of them
      offset - the offset (starting at 0) into the list of documents
      Returns:
      the query result
      Since:
      7.10-HF25, 8.10-HF06, 9.2

    • queryProjection

      PartialList<Map<String,Serializable>> queryProjection(String query, long limit, long offset, boolean countTotal)
      Executes the given NXQL query and returns the result that matches the filter.
      Parameters:
      query - the query to execute
      limit - the maximum number of documents to retrieve, or 0 for all of them
      offset - the offset (starting at 0) into the list of documents
      countTotal - if true, return a PartialList that includes a total size of the underlying list (size if there was no limit or offset)
      Returns:
      the query result
      Since:
      7.10-HF25, 8.10-HF06, 9.2

    • queryProjection

      PartialList<Map<String,Serializable>> queryProjection(String query, String queryType, boolean distinctDocuments, long limit, long offset, long countUpTo, Object... params)
      Executes the given NXQL query and returns the result that matches the filter.
      Parameters:
      query - the query to execute
      queryType - the query type, like "NXQL"
      distinctDocuments - if true then a maximum of one row per document will be returned
      limit - the maximum number of documents to retrieve, or 0 for all of them
      offset - the offset (starting at 0) into the list of documents
      countUpTo - if -1, return a PartialList that includes a total size of the underlying list (size if there was no limit or offset).
      If 0, don't return the total size of the underlying list.
      If n, return the total size of the underlying list when the size is smaller than n else return a total size of -1.
      params - optional query-type-dependent parameters
      Returns:
      the query result
      Since:
      7.10-HF25, 8.10-HF06, 9.2

    • scroll

      ScrollResult<String> scroll(String query, int batchSize, int keepAliveSeconds)
      Executes the given query and returns the first batch of results containing id of documents, next batch must be requested within the keepAliveSeconds delay.
      Parameters:
      query - The NXQL query to execute
      batchSize - The expected result batch size, note that more results can be returned when the backend don't implement properly this feature
      keepAliveSeconds - The scroll context lifetime in seconds
      Returns:
      A ScrollResult including the search results and a scroll id, to be passed to the subsequent calls to scroll(String)
      Since:
      8.4

    • scroll

      ScrollResult<String> scroll(String scrollId)
      Get the next batch of results containing id of documents, the scrollId is part of the previous ScrollResult response.
      Throws:
      NuxeoException - when the scrollId is unknown or when the scroll operation has timed out
      Since:
      8.4

    • getAvailableSecurityPermissions

      List<String> getAvailableSecurityPermissions()
      Retrieves the available security permissions existing in the system.

      Returns:
      a raw list of permission names, either basic or group names

    • makeRecord

      void makeRecord(DocumentRef docRef)
      Turns the document into an enforced record.

      A record is a document with specific capabilities related to mandatory retention until a given date, and legal holds. In addition, its main blob receives special treatment from the document blob manager to make sure it's never shared with another blob at the storage level, and is deleted as soon as the record is deleted.

      If the document is already a record, this method has no effect.

      The permission "MakeRecord" is required.

      Parameters:
      docRef - the document
      Since:
      11.1
      See Also:

    • makeFlexibleRecord

      default void makeFlexibleRecord(DocumentRef docRef)
      Turns the document into a flexible record.

      A record is a document with specific capabilities related to mandatory retention until a given date. Unlike the enforced record, the flexible record blob has no special treatment.

      Setting a legal hold (setLegalHold(DocumentRef, boolean, String) on a flexible record will turn it into an enforced record.

      If the document is already a flexible record, this method has no effect. It is not allowed to turn an enforced record into a flexible record and an IllegalStateException will be raised.

      The permission "MakeRecord" is required.

      Parameters:
      docRef - the document
      Throws:
      IllegalStateException - if the document is already an enforced record
      Since:
      2023.1
      See Also:

    • isRecord

      boolean isRecord(DocumentRef docRef)
      Checks if the document is a record.
      Parameters:
      docRef - the document
      Returns:
      true if the document is a record, false otherwise
      Since:
      11.1
      See Also:

    • isEnforcedRecord

      default boolean isEnforcedRecord(DocumentRef docRef)
      Checks if the document is an enforced record.
      Parameters:
      docRef - the document
      Returns:
      true if the document is an enforced record, false otherwise
      Since:
      2023.1
      See Also:

    • isFlexibleRecord

      default boolean isFlexibleRecord(DocumentRef docRef)
      Checks if the document is a flexible record.
      Parameters:
      docRef - the document
      Returns:
      true if the document is a flexible record, false otherwise
      Since:
      2023.1
      See Also:

    • setRetainUntil

      void setRetainUntil(DocumentRef docRef, Calendar retainUntil, String comment) throws PropertyException
      Sets the retention date on the document (a record).

      If no previous retention date was set, or if the previous retention date was indeterminate, or if the previous retention date was before the given value, then the retention date is set to the given value.

      If the previous retention date was after the given value (that is, if trying to reduce the retention time), an exception is thrown.

      If the given value is null and the previous retention date is in the past (it has already expired), then the retention date is set to null.

      The permission "SetRetention" is required.

      Parameters:
      docRef - the document (a record)
      retainUntil - the new retention date
      comment - an optional comment passed to the associated events
      Throws:
      PropertyException - if trying to reduce the retention time, or if the document is not a record
      Since:
      11.1
      See Also:

    • unsetRetainUntil

      default void unsetRetainUntil(DocumentRef docRef)
      Removes the retainUntil date, this operation is allowed only for a flexible record.
      Parameters:
      docRef - the document (a flexible record)
      Throws:
      PropertyException - if the document is not a flexible record
      DocumentSecurityException - if the current user does not have the SecurityConstants.UNSET_RETENTION permission
      Since:
      2023.1

    • getRetainUntil

      Calendar getRetainUntil(DocumentRef docRef)
      Gets the retention date for the document.
      Parameters:
      docRef - the document
      Returns:
      the retention date, or "SetRetention" for a retention in the indeterminate future, or null if there is no retention date
      Since:
      11.1
      See Also:

    • setLegalHold

      void setLegalHold(DocumentRef docRef, boolean hold, String comment)
      Sets or removes the legal hold on the document (a record).

      Setting a legal hold on a flexible record will turn it into an enforced record. It will remain enforced even after unsetting the legal hold.

      The permission "ManageLegalHold" is required.

      Parameters:
      docRef - the document (a record)
      hold - true to set a legal hold, false to remove it
      comment - an optional comment passed to the associated events
      Throws:
      PropertyException - if the document is not a record
      Since:
      11.1
      See Also:

    • hasLegalHold

      boolean hasLegalHold(DocumentRef docRef)
      Checks if the document has a legal hold set.
      Parameters:
      docRef - the document
      Returns:
      true if a legal hold has been set on the document, false otherwise
      Since:
      11.1
      See Also:

    • isUnderRetentionOrLegalHold

      boolean isUnderRetentionOrLegalHold(DocumentRef docRef)
      Checks if the document has a retention date in the future or has a legal hold.
      Parameters:
      docRef - the document
      Returns:
      true if the document has a retention date in the future or if it has a legal hold, false otherwise
      Since:
      11.1
      See Also:

    • isRetentionActive

      @Deprecated boolean isRetentionActive(DocumentRef docRef)
      Deprecated.
      since 11.1, unused, use hasLegalHold(org.nuxeo.ecm.core.api.DocumentRef) instead
      Checks whether a document is under active retention.
      Parameters:
      docRef - the document reference
      Returns:
      true if the document is under active retention
      Since:
      9.3

    • setRetentionActive

      @Deprecated void setRetentionActive(DocumentRef docRef, boolean retentionActive)
      Deprecated.
      since 11.1, unused, use setLegalHold(org.nuxeo.ecm.core.api.DocumentRef, boolean, java.lang.String) instead
      Sets or unsets a document as under active retention.
      Parameters:
      docRef - the document reference
      retentionActive - whether the retention should be set or unset as active
      Since:
      9.3

    • isTrashed

      boolean isTrashed(DocumentRef docRef)
      Checks if this document is in the trash.
      Parameters:
      docRef - the document reference
      Returns:
      true if the document is in the trash, false otherwise.
      Since:
      10.1

    • getCurrentLifeCycleState

      String getCurrentLifeCycleState(DocumentRef docRef)
      Returns the life cycle of the document.
      Parameters:
      docRef - the document reference
      Returns:
      the life cycle as a string
      Implementation Note:
      See org.nuxeo.ecm.core.lifecycle package

    • getLifeCyclePolicy

      String getLifeCyclePolicy(DocumentRef docRef)
      Returns the life cycle policy of the document.
      Parameters:
      docRef - the document reference
      Returns:
      the life cycle policy
      Implementation Note:
      See org.nuxeo.ecm.core.lifecycle package

    • followTransition

      boolean followTransition(DocumentRef docRef, String transition) throws LifeCycleException
      Follows a given life cycle transition.

      This will update the current life cycle of the document.

      Parameters:
      docRef - the document reference
      transition - the name of the transition to follow
      Returns:
      a boolean representing the status if the operation
      Throws:
      LifeCycleException - if the transition cannot be followed

    • followTransition

      boolean followTransition(DocumentModel doc, String transition) throws LifeCycleException
      Follows a given life cycle transition.

      This will update the current life cycle of the document.

      Parameters:
      doc - the document model
      transition - the name of the transition to follow
      Returns:
      a boolean representing the status if the operation
      Throws:
      LifeCycleException - if the transition cannot be followed

    • getAllowedStateTransitions

      Collection<String> getAllowedStateTransitions(DocumentRef docRef)
      Gets the allowed state transitions for this document.
      Parameters:
      docRef - the document reference
      Returns:
      a collection of state transitions as string

    • reinitLifeCycleState

      void reinitLifeCycleState(DocumentRef docRef)
      Reinitializes the life cycle state of the document to its default state.
      Parameters:
      docRef - the document
      Since:
      5.4.2

    • getDataModelsField

      Object[] getDataModelsField(DocumentRef[] docRefs, String schema, String field)
      Retrieves the given field value from the given schema for all the given documents.
      Parameters:
      docRefs - the document references
      schema - the schema
      field - the field name
      Returns:
      the field values in the same order as the given docRefs

    • getParentDocumentRefs

      DocumentRef[] getParentDocumentRefs(DocumentRef docRef)
      Creates an array with all parent refs starting from the given document up to the root. So the return value will have [0] = parent ref; [1] = parent parent ref... etc.
      Returns:
      an array with ancestor documents ref

    • getDataModelsFieldUp

      Object[] getDataModelsFieldUp(DocumentRef docRef, String schema, String field)
      Retrieves the given field value from the given schema for the given document along with all its parent documents.
      Parameters:
      docRef - the document reference
      schema - the schema
      field - the field name
      Returns:
      an array with field values of all documents on the path from the given document to the root

    • setLock

      Lock setLock(DocumentRef docRef) throws LockException
      Sets a lock on the given document.
      Parameters:
      docRef - the document reference
      Returns:
      the lock info that was set
      Throws:
      LockException - if the document is already locked by another user
      Since:
      5.4.2

    • getLockInfo

      Lock getLockInfo(DocumentRef docRef)
      Gets the lock info on the given document.

      Lock info is never cached, and needs to use a separate transaction in a separate thread, so care should be taken to not call this method needlessly.

      Parameters:
      docRef - the document reference
      Returns:
      the lock info if the document is locked, or null otherwise
      Since:
      5.4.2

    • removeLock

      Lock removeLock(DocumentRef docRef) throws LockException
      Removes the lock on the given document.

      The caller principal should be the same as the one who set the lock or to belongs to the administrator group, otherwise an exception will be throw.

      If the document was not locked, does nothing.

      Returns the previous lock info.

      Parameters:
      docRef - the document to unlock
      Returns:
      the removed lock info, or null if there was no lock
      Throws:
      LockException - if the document is locked by someone else
      Since:
      5.4.2

    • applyDefaultPermissions

      void applyDefaultPermissions(String userOrGroupName)
      Applies default Read permissions on root JCR Document for the given user or group name. It can only be called by Administrators.

      Usage: As an administrator, you may want to add new users or groups. This method needs to be called to grand default reading permissions on the root document of the repository for the newly created users/groups.

    • publishDocument

      DocumentModel publishDocument(DocumentModel docToPublish, DocumentModel section)
      Publishes the document in a section overwriting any existing proxy to the same document. This is simmilar to publishDocument(docToPublish, section, true);
      Returns:
      The proxy document that was created
      Since:
      1.4.1 for the case where docToPublish is a proxy

    • publishDocument

      DocumentModel publishDocument(DocumentModel docToPublish, DocumentModel section, boolean overwriteExistingProxy)
      Publishes the document in a section.
      Returns:
      The proxy document that was created

    • getProxies

      DocumentModelList getProxies(DocumentRef docRef, DocumentRef folderRef)
      Finds the proxies for a document. If the parent is not null, the search will be limited to its direct children.

      If the document is a version, then only proxies to that version will be looked up.

      If the document is a proxy, then all similar proxies (pointing to any version of the same versionable) are retrieved.

      Parameters:
      docRef - the target document for the proxies
      folderRef - the folder where proxies are located or null
      Returns:
      the list of the proxies. An empty list is returned if no proxy are found
      Since:
      1.4.1 for the case where docRef is a proxy

    • getRetainedProperties

      List<String> getRetainedProperties(DocumentRef docRef)
      Gets the retained property xpaths of this document at the time it became a record.
      Returns:
      the retained properties
      Since:
      2021.32

    • getSuperParentType

      String getSuperParentType(DocumentModel doc)
      Returns the type of his parent SuperSpace (workspace, section, etc.). SuperSpace is qualified by the SuperSpace facet.

    • getSuperSpace

      DocumentModel getSuperSpace(DocumentModel doc)
      Returns the parent SuperSpace (workspace, section, etc.). SuperSpace is qualified by the SuperSpace facet.
      Returns:
      DocumentModel of SuperSpace

    • getRepositoryName

      String getRepositoryName()
      Returns the repository name against which this core session is bound.
      Returns:
      the repository name used currently used as an identifier

    • getDocumentSystemProp

      <T extends Serializable> T getDocumentSystemProp(DocumentRef ref, String systemProperty, Class<T> type)
      Gets system property of the specified type for the document ref.

    • setDocumentSystemProp

      <T extends Serializable> void setDocumentSystemProp(DocumentRef ref, String systemProperty, T value)
      Sets given value as a system property.

    • orderBefore

      void orderBefore(DocumentRef parent, String src, String dest)
      Given a parent document, order the source child before the destination child. The source and destination must be name of child documents of the given parent document. (a document name can be retrieved using docModel.getName()) To place the source document at the end of the children list use a null destination node.
      Parameters:
      parent - the parent document
      src - the document to be moved (ordered)
      dest - the document before which the reordered document will be placed If null the source document will be placed at the end of the children list

    • refreshDocument

      DocumentModel.DocumentModelRefresh refreshDocument(DocumentRef ref, int refreshFlags, String[] schemas)
      Internal method - it is used internally by DocumentModel.refresh()

      Get fresh data from a document given a description of what kind of data should be refetched.

      The refresh information is specified using a bit mask. See DocumentModel for all accepted flags.

      When the flag DocumentModel.REFRESH_CONTENT_IF_LOADED is specified a third argument must be passed representing the schema names for document parts to refresh. This argument is ignored if the flag is not specified or no schema names are provided

      Parameters:
      ref - the document reference
      refreshFlags - refresh flags as defined in DocumentModel
      schemas - the schema names if a partial content refresh is required
      Returns:
      a DocumentModelRefresh object

    • getPermissionsToCheck

      String[] getPermissionsToCheck(String permission)
      Provides the full list of all permissions or groups of permissions that contain the given one (inclusive). It makes the method org.nuxeo.ecm.core.security.SecurityService#getPermissionsToCheck(String) available remotely.
      Returns:
      the list, as an array of strings.

    • adaptFirstMatchingDocumentWithFacet

      <T extends DetachedAdapter> T adaptFirstMatchingDocumentWithFacet(DocumentRef docRef, String facet, Class<T> adapterClass)
      Find the first parent with the given facet and adapt it on the adapterClass.

      This method does not check the permissions on the document to be adapted of this CoreSession's Principal, and so the adapter must not need other schemas from the DocumentModel except the schemas related to the given facet.

      Returns:
      the first parent with the given facet adapted, or null if no parent found or the document does not support the given adapterClass.
      Since:
      5.4.2

    • getBinaryFulltext

      Map<String,String> getBinaryFulltext(DocumentRef ref)
      Gets the fulltext extracted from the binary fields. We defined a new API for that to avoid to store in the cache the fulltext properties which could be huge. This method handle if document is a proxy or not. Historically, VCS doesn't store fulltext properties for proxies (note that DBS does).
      Parameters:
      ref - the document reference
      Returns:
      the fulltext map or null if not supported.
      Since:
      5.9.3

    • getChangeToken

      String getChangeToken(DocumentRef ref)
      Gets the current change token for the document.

      The change token is an opaque string which is modified every time the document is changed.

      Before saving a document through saveDocument(org.nuxeo.ecm.core.api.DocumentModel) it's possible to pass an expected change token in the document context data through doc.putContextData(CoreSession.CHANGE_TOKEN, expectedChangeToken). If the change token does not match the stored one, it means that a concurrent update happened, and a ConcurrentUpdateException will be thrown.

      Parameters:
      ref - the document reference
      Returns:
      the change token
      Since:
      9.1
      See Also:

    • getOrCreateDocument

      DocumentModel getOrCreateDocument(DocumentModel docModel)
      Gets a document if it exists, otherwise creates it. This is done atomically to prevent different threads from trying to create the same document. If the document did not exist and is therefore created, the current transaction is committed and the newly-created document is also committed in its own transaction.

      WARNING: As the current transaction is impacted, using this method instead of createDocument(DocumentModel) could lead to inconsistent behaviour in case of rollback.

      Parameters:
      docModel - the document model
      Returns:
      the existing or created document
      Since:
      9.3

    • getOrCreateDocument

      DocumentModel getOrCreateDocument(DocumentModel docModel, Function<DocumentModel,DocumentModel> postCreate)
      Gets a document if it exists, otherwise creates it. This is done atomically to prevent different threads from trying to create the same document. If the document did not exist and is therefore created, the current transaction is committed and the newly-created document is also committed in its own transaction.

      WARNING: As the current transaction is impacted, using this method instead of createDocument(DocumentModel) could lead to inconsistent behaviour in case of rollback.

      Parameters:
      docModel - the document model
      postCreate - the function to apply after creating the document
      Returns:
      the existing or created document
      Since:
      9.3

    • replaceBlobDigest

      String replaceBlobDigest(DocumentRef docRef, String key, String newKey, String newDigest)
      Visits the blobs of a document and, for those with a matching key, replace their key and digest with new ones.
      Parameters:
      docRef - the document reference
      key - the bob key to look for
      newKey - the new key
      newDigest - the new digest
      Returns:
      the old digest if at least one replacement was done, null otherwise
      Since:
      11.5