/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
* regarding copyright ownership. The ASF licenses this file
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied. See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.apache.chemistry.opencmis.client.api;
import java.io.Serializable;
import java.math.BigInteger;
import java.util.Collection;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.Set;
import org.apache.chemistry.opencmis.commons.data.Ace;
import org.apache.chemistry.opencmis.commons.data.Acl;
import org.apache.chemistry.opencmis.commons.data.BulkUpdateObjectIdAndChangeToken;
import org.apache.chemistry.opencmis.commons.data.ContentStream;
import org.apache.chemistry.opencmis.commons.data.RepositoryInfo;
import org.apache.chemistry.opencmis.commons.definitions.TypeDefinition;
import org.apache.chemistry.opencmis.commons.enums.AclPropagation;
import org.apache.chemistry.opencmis.commons.enums.IncludeRelationships;
import org.apache.chemistry.opencmis.commons.enums.RelationshipDirection;
import org.apache.chemistry.opencmis.commons.enums.UnfileObject;
import org.apache.chemistry.opencmis.commons.enums.VersioningState;
import org.apache.chemistry.opencmis.commons.exceptions.CmisBaseException;
import org.apache.chemistry.opencmis.commons.exceptions.CmisObjectNotFoundException;
import org.apache.chemistry.opencmis.commons.spi.CmisBinding;
/**
* A session is a connection to a CMIS repository with a specific user.
* <p>
* CMIS itself is stateless. OpenCMIS uses the concept of a session to cache
* data across calls and to deal with user authentication. The session object is
* also used as entry point to all CMIS operations and objects. Because a
* session is only a client side concept, the session object needs not to be
* closed or released when it's not needed anymore.
* <p>
* Not all operations provided by this API might be supported by the connected
* repository. Either OpenCMIS or the repository will throw an exception if an
* unsupported operation is called. The capabilities of the repository can be
* discovered by evaluating the repository info (see
* {@link #getRepositoryInfo()}).
* <p>
* Almost all methods might throw exceptions derived from
* {@link CmisBaseException} which is a runtime exception. See the CMIS
* specification for a list of all operations and their exceptions. Note that
* some incompliant repositories might throw other exception than you expect.
* <p>
* Refer to the <a href="http://docs.oasis-open.org/cmis/CMIS/v1.0/os/">CMIS 1.0
* specification</a> or the
* <a href="http://docs.oasis-open.org/cmis/CMIS/v1.0/os/">CMIS 1.1
* specification</a> for details about the domain model, terms, concepts, base
* types, properties, IDs and query names, query language, etc.
* </p>
*/
public interface Session extends Serializable {
/**
* Clears all cached data.
*/
void clear();
// session context
/**
* Returns the underlying binding object.
*
* @return the binding object, not {@code null}
*/
CmisBinding getBinding();
/**
* Returns the session parameters that were used to create this session.
*
* @return the session parameters, a unmodifiable Map, not {@code null}
*/
Map<String, String> getSessionParameters();
/**
* Returns the current default operation parameters for filtering, paging
* and caching.
*
* <p>
* <em>Please note:</em> The returned object is not thread-safe and should
* only be modified right after the session has been created and before the
* session object has been used. In order to change the default context in
* thread-safe manner, create a new {@link OperationContext} object and use
* {@link #setDefaultContext(OperationContext)} to apply it.
* </p>
*
* @return the default operation context, not {@code null}
*/
OperationContext getDefaultContext();
/**
* Sets the current session parameters for filtering, paging and caching.
*
* @param context
* the {@code OperationContext} to be used for the session; if
* {@code null}, a default context is used
*/
void setDefaultContext(OperationContext context);
/**
* Creates a new operation context object.
*
* @return the newly created operation context object
*/
OperationContext createOperationContext();
/**
* Creates a new operation context object with the given properties.
*
* @param filter
* the property filter, a comma separated string of <em>query
* names</em> or "*" for all properties or {@code null} to let
* the repository determine a set of properties
* @param includeAcls
* indicates whether ACLs should be included or not
* @param includeAllowableActions
* indicates whether Allowable Actions should be included or not
* @param includePolicies
* indicates whether policies should be included or not
* @param includeRelationships
* enum that indicates if and which relationships should be
* includes
* @param renditionFilter
* the rendition filter or {@code null} for no renditions
* @param includePathSegments
* indicates whether path segment or the relative path segment
* should be included or not
* @param orderBy
* the object order, a comma-separated list of <em>query
* names</em> and the ascending modifier "ASC" or the descending
* modifier "DESC" for each query name
* @param cacheEnabled
* flag that indicates if the object cache should be used
* @param maxItemsPerPage
* the max items per batch
*
* @return the newly created operation context object
*
* @see OperationContext
*/
OperationContext createOperationContext(Set<String> filter, boolean includeAcls, boolean includeAllowableActions,
boolean includePolicies, IncludeRelationships includeRelationships, Set<String> renditionFilter,
boolean includePathSegments, String orderBy, boolean cacheEnabled, int maxItemsPerPage);
/**
* Creates an object ID from a String.
*
* @return the object ID object
*/
ObjectId createObjectId(String id);
// localization
/**
* Get the current locale to be used for this session.
*
* @return the current locale, may be {@code null}
*/
Locale getLocale();
// services
/**
* Returns the repository info of the repository associated with this
* session.
*
* @return the repository info, not {@code null}
*
* @cmis 1.0
*/
RepositoryInfo getRepositoryInfo();
/**
* Gets a factory object that provides methods to create the objects used by
* this API.
*
* @return the repository info, not {@code null}
*/
ObjectFactory getObjectFactory();
// types
/**
* Gets the definition of a type.
*
* @param typeId
* the ID of the type
*
* @return the type definition
*
* @throws CmisObjectNotFoundException
* if a type with the given type ID doesn't exist
*
* @cmis 1.0
*/
ObjectType getTypeDefinition(String typeId);
/**
* Gets the definition of a type.
*
* @param typeId
* the ID of the type
* @param useCache
* specifies if the type definition should be first looked up in
* the type definition cache, if it is set to {@code false} or
* the type definition is not in the cache, the type definition
* is loaded from the repository
*
* @return the type definition
*
* @throws CmisObjectNotFoundException
* if a type with the given type ID doesn't exist
*
* @cmis 1.0
*/
ObjectType getTypeDefinition(String typeId, boolean useCache);
/**
* Gets the type children of a type.
*
* @param typeId
* the type ID or {@code null} to request the base types
* @param includePropertyDefinitions
* indicates whether the property definitions should be included
* or not
* @return the type iterator, not {@code null}
*
* @throws CmisObjectNotFoundException
* if a type with the given type ID doesn't exist
*
* @cmis 1.0
*/
ItemIterable<ObjectType> getTypeChildren(String typeId, boolean includePropertyDefinitions);
/**
* Gets the type descendants of a type.
*
* @param typeId
* the type ID or {@code null} to request the base types
* @param depth
* the tree depth, must be greater than 0 or -1 for infinite
* depth
* @param includePropertyDefinitions
* indicates whether the property definitions should be included
* or not
* @return the tree of types
*
* @throws CmisObjectNotFoundException
* if a type with the given type ID doesn't exist
*
* @cmis 1.0
*/
List<Tree<ObjectType>> getTypeDescendants(String typeId, int depth, boolean includePropertyDefinitions);
/**
* Creates a new type.
*
* @param type
* the type definition
*
* @return the new type definition
*
* @cmis 1.1
*/
ObjectType createType(TypeDefinition type);
/**
* Updates an existing type.
*
* @param type
* the type definition updates
*
* @return the updated type definition
*
* @cmis 1.1
*/
ObjectType updateType(TypeDefinition type);
/**
* Deletes a type.
*
* @param typeId
* the ID of the type to delete
*
* @cmis 1.1
*/
void deleteType(String typeId);
// navigation
/**
* Gets the root folder of the repository.
*
* @return the root folder object, not {@code null}
*
* @cmis 1.0
*/
Folder getRootFolder();
/**
* Gets the root folder of the repository with the given
* {@link OperationContext}.
*
* @return the root folder object, not {@code null}
*
* @cmis 1.0
*/
Folder getRootFolder(OperationContext context);
/**
* Returns all checked out documents.
*
* @see Folder#getCheckedOutDocs()
*
* @cmis 1.0
*/
ItemIterable<Document> getCheckedOutDocs();
/**
* Returns all checked out documents with the given {@link OperationContext}
* .
*
* @see Folder#getCheckedOutDocs(OperationContext)
*
* @cmis 1.0
*/
ItemIterable<Document> getCheckedOutDocs(OperationContext context);
/**
* Returns a CMIS object from the session cache. If the object is not in the
* cache or the cache is turned off per default {@link OperationContext}, it
* will load the object from the repository and puts it into the cache.
* <p>
* This method might return a stale object if the object has been found in
* the cache and has been changed in or removed from the repository. Use
* {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
* update the object if necessary.
*
* @param objectId
* the object ID
*
* @return the requested object
*
* @throws CmisObjectNotFoundException
* if an object with the given ID doesn't exist
*
* @see #getObject(String)
*
* @cmis 1.0
*/
CmisObject getObject(ObjectId objectId);
/**
* Returns a CMIS object from the session cache. If the object is not in the
* cache or the given {@link OperationContext} has caching turned off, it
* will load the object from the repository and puts it into the cache.
* <p>
* This method might return a stale object if the object has been found in
* the cache and has been changed in or removed from the repository. Use
* {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
* update the object if necessary.
*
* @param objectId
* the object ID
* @param context
* the {@link OperationContext} to use
*
* @return the requested object
*
* @throws CmisObjectNotFoundException
* if an object with the given ID doesn't exist
*
* @see #getObject(String, OperationContext)
*
* @cmis 1.0
*/
CmisObject getObject(ObjectId objectId, OperationContext context);
/**
* Returns a CMIS object from the session cache. If the object is not in the
* cache or the cache is turned off per default {@link OperationContext}, it
* will load the object from the repository and puts it into the cache.
* <p>
* This method might return a stale object if the object has been found in
* the cache and has been changed in or removed from the repository. Use
* {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
* update the object if necessary.
*
* @param objectId
* the object ID
*
* @return the requested object
*
* @throws CmisObjectNotFoundException
* if an object with the given ID doesn't exist
*
* @see #getObject(ObjectId)
*
* @cmis 1.0
*/
CmisObject getObject(String objectId);
/**
* Returns a CMIS object from the session cache. If the object is not in the
* cache or the given {@link OperationContext} has caching turned off, it
* will load the object from the repository and puts it into the cache.
* <p>
* This method might return a stale object if the object has been found in
* the cache and has been changed in or removed from the repository. Use
* {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
* update the object if necessary.
*
* @param objectId
* the object ID
* @param context
* the {@link OperationContext} to use
*
* @return the requested object
*
* @throws CmisObjectNotFoundException
* if an object with the given ID doesn't exist
*
* @see #getObject(ObjectId, OperationContext)
*
* @cmis 1.0
*/
CmisObject getObject(String objectId, OperationContext context);
/**
* Returns a CMIS object from the session cache. If the object is not in the
* cache or the cache is turned off per default {@link OperationContext}, it
* will load the object from the repository and puts it into the cache.
* <p>
* This method might return a stale object if the object has been found in
* the cache and has been changed in or removed from the repository. Use
* {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
* update the object if necessary.
*
* @param path
* the object path
*
* @return the requested object
*
* @throws CmisObjectNotFoundException
* if an object with the given ID doesn't exist
*
* @cmis 1.0
*/
CmisObject getObjectByPath(String path);
/**
* Returns a CMIS object from the session cache. If the object is not in the
* cache or the given {@link OperationContext} has caching turned off, it
* will load the object from the repository and puts it into the cache.
* <p>
* This method might return a stale object if the object has been found in
* the cache and has been changed in or removed from the repository. Use
* {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
* update the object if necessary.
*
* @param path
* the object path
* @param context
* the {@link OperationContext} to use
*
* @return the requested object
*
* @throws CmisObjectNotFoundException
* if an object with the given ID doesn't exist
*
* @cmis 1.0
*/
CmisObject getObjectByPath(String path, OperationContext context);
/**
* Returns a CMIS object from the session cache. If the object is not in the
* cache or the cache is turned off per default {@link OperationContext}, it
* will load the object from the repository and puts it into the cache.
* <p>
* This method might return a stale object if the object has been found in
* the cache and has been changed in or removed from the repository. Use
* {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
* update the object if necessary.
*
* @param parentPath
* the path of the parent folder
* @param name
* the (path segment) name of the object in the folder
*
* @return the requested object
*
* @throws CmisObjectNotFoundException
* if an object with the given ID doesn't exist
*
* @cmis 1.0
*/
CmisObject getObjectByPath(String parentPath, String name);
/**
* Returns a CMIS object from the session cache. If the object is not in the
* cache or the given {@link OperationContext} has caching turned off, it
* will load the object from the repository and puts it into the cache.
* <p>
* This method might return a stale object if the object has been found in
* the cache and has been changed in or removed from the repository. Use
* {@link CmisObject#refresh()} and {@link CmisObject#refreshIfOld(long)} to
* update the object if necessary.
*
* @param parentPath
* the path of the parent folder
* @param name
* the (path segment) name of the object in the folder
* @param context
* the {@link OperationContext} to use
*
* @return the requested object
*
* @throws CmisObjectNotFoundException
* if an object with the given ID doesn't exist
*
* @cmis 1.0
*/
CmisObject getObjectByPath(String parentPath, String name, OperationContext context);
/**
* Returns the latest version in a version series.
*
* Some repositories throw an exception if the document is not versionable;
* others just return the unversioned document. To avoid surprises, check
* first whether the document is versionable or not.
*
* @param objectId
* the document ID of an arbitrary version in the version series
*
* @return the latest document version
*
* @cmis 1.0
*/
Document getLatestDocumentVersion(ObjectId objectId);
/**
* Returns the latest version in a version series.
*
* Some repositories throw an exception if the document is not versionable;
* others just return the unversioned document. To avoid surprises, check
* first whether the document is versionable or not.
*
* @param objectId
* the document ID of an arbitrary version in the version series
* @param context
* the {@link OperationContext} to use
*
* @return the latest document version
*
* @cmis 1.0
*/
Document getLatestDocumentVersion(ObjectId objectId, OperationContext context);
/**
* Returns the latest version in a version series.
*
* Some repositories throw an exception if the document is not versionable;
* others just return the unversioned document. To avoid surprises, check
* first whether the document is versionable or not.
*
* If {@code major} == {@code true} and the version series doesn't contain a
* major version, the repository is supposed to throw a
* {@link CmisObjectNotFoundException}.
*
* @param objectId
* the document ID of an arbitrary version in the version series
* @param major
* if {@code true} the latest major version will be returned,
* otherwise the very last version will be returned
* @param context
* the {@link OperationContext} to use
*
* @return the latest document version
*
* @cmis 1.0
*/
Document getLatestDocumentVersion(ObjectId objectId, boolean major, OperationContext context);
/**
* Returns the latest version in a version series.
*
* Some repositories throw an exception if the document is not versionable;
* others just return the unversioned document. To avoid surprises, check
* first whether the document is versionable or not.
*
* @param objectId
* the document ID of an arbitrary version in the version series
*
* @return the latest document version
*
* @cmis 1.0
*/
Document getLatestDocumentVersion(String objectId);
/**
* Returns the latest version in a version series.
*
* Some repositories throw an exception if the document is not versionable;
* others just return the unversioned document. To avoid surprises, check
* first whether the document is versionable or not.
*
* @param objectId
* the document ID of an arbitrary version in the version series
* @param context
* the {@link OperationContext} to use
*
* @return the latest document version
*
* @cmis 1.0
*/
Document getLatestDocumentVersion(String objectId, OperationContext context);
/**
* Returns the latest version in a version series.
*
* Some repositories throw an exception if the document is not versionable;
* others just return the unversioned document. To avoid surprises, check
* first whether the document is versionable or not.
*
* If {@code major} == {@code true} and the version series doesn't contain a
* major version, the repository is supposed to throw a
* {@link CmisObjectNotFoundException}.
*
* @param objectId
* the document ID of an arbitrary version in the version series
* @param major
* if {@code true} the latest major version will be returned,
* otherwise the very last version will be returned
* @param context
* the {@link OperationContext} to use
*
* @return the latest document version
*
* @cmis 1.0
*/
Document getLatestDocumentVersion(String objectId, boolean major, OperationContext context);
/**
* Checks if an object with given object ID exists in the repository and is
* visible for the current user.
*
* If the object doesn't exist (anymore), it is removed from the cache.
*
* @param objectId
* the object ID
* @return {@code true} if the object exists in the repository,
* {@code false} otherwise
*
* @cmis 1.0
*/
boolean exists(ObjectId objectId);
/**
* Checks if an object with given object ID exists in the repository and is
* visible for the current user.
*
* If the object doesn't exist (anymore), it is removed from the cache.
*
* @param objectId
* the object ID
* @return {@code true} if the object exists in the repository,
* {@code false} otherwise
*
* @cmis 1.0
*/
boolean exists(String objectId);
/**
* Checks if an object with given path exists in the repository and is
* visible for the current user.
*
* If the object doesn't exist (anymore), it is removed from the cache.
*
* @param path
* the path
* @return {@code true} if the object exists in the repository,
* {@code false} otherwise
*
* @cmis 1.0
*/
boolean existsPath(String path);
/**
* Checks if an object with given path exists in the repository and is
* visible for the current user.
*
* If the object doesn't exist (anymore), it is removed from the cache.
*
* @param parentPath
* the path of the parent folder
* @param name
* the (path segment) name of the object in the folder
*
* @return the requested object
*
* @throws CmisObjectNotFoundException
* if an object with the given ID doesn't exist
*
* @cmis 1.0
*/
boolean existsPath(String parentPath, String name);
/**
* Removes the given object from the cache.
*
* @param objectId
* object ID
*
* @see #removeObjectFromCache(String)
*/
void removeObjectFromCache(ObjectId objectId);
/**
* Removes the given object from the cache.
*
* @param objectId
* object ID
*/
void removeObjectFromCache(String objectId);
// discovery
/**
* Sends a query to the repository. Refer to the CMIS specification for the
* CMIS query language syntax.
*
* @param statement
* the query statement (CMIS query language)
* @param searchAllVersions
* specifies whether non-latest document versions should be
* included or not, {@code true} searches all document versions,
* {@code false} only searches latest document versions
*
* @return an {@link Iterable} to iterate over the query result
*
* @cmis 1.0
*/
ItemIterable<QueryResult> query(String statement, boolean searchAllVersions);
/**
* Sends a query to the repository using the given {@link OperationContext}.
* (See CMIS spec "2.1.10 Query".)
*
* @param statement
* the query statement (CMIS query language)
* @param searchAllVersions
* specifies whether non-latest document versions should be
* included or not, {@code true} searches all document versions,
* {@code false} only searches latest document versions
* @param context
* the operation context to use
*
* @return an {@link Iterable} to iterate over the query result
*
* @cmis 1.0
*/
ItemIterable<QueryResult> query(String statement, boolean searchAllVersions, OperationContext context);
/**
* Builds a CMIS query and returns the query results as an iterator of
* {@link CmisObject} objects.
*
* @param typeId
* the ID of the object type
* @param where
* the WHERE part of the query
* @param searchAllVersions
* specifies whether non-latest document versions should be
* included or not, {@code true} searches all document versions,
* {@code false} only searches latest document versions
* @param context
* the operation context to use
*
* @return an {@link Iterable} to iterate over the objects
*
* @cmis 1.0
*/
ItemIterable<CmisObject> queryObjects(String typeId, String where, boolean searchAllVersions,
OperationContext context);
/**
* Creates a query statement.
* <p>
* Sample code:
*
* <pre>
* QueryStatement stmt = session
* .createQueryStatement("SELECT ?, ? FROM ? WHERE ? > TIMESTAMP ? AND IN_FOLDER(?) OR ? IN (?)");
* </pre>
*
* @param statement
* the query statement with placeholders ('?'), see
* {@link QueryStatement} for details
*
* @return a new query statement object
*
* @see QueryStatement
*
* @cmis 1.0
*/
QueryStatement createQueryStatement(String statement);
/**
* Creates a query statement for a query of one primary type joined by zero
* or more secondary types.
* <p>
* Sample code:
*
* <pre>
* List<String> select = new ArrayList<String>();
* select.add("cmis:name");
* select.add("SecondaryStringProp");
*
* Map<String, String> from = new HashMap<String, String>();
* from.put("d", "cmis:document");
* from.put("s", "MySecondaryType");
*
* String where = "d.cmis:name LIKE ?";
*
* List<String> orderBy = new ArrayList<String>();
* orderBy.add("cmis:name");
* orderBy.add("SecondaryIntegerProp");
*
* QueryStatement stmt = session.createQueryStatement(select, from, where, orderBy);
* </pre>
*
* Generates something like this:
*
* <pre>
* SELECT d.cmis:name,s.SecondaryStringProp FROM cmis:document AS d JOIN MySecondaryType AS s ON d.cmis:objectId=s.cmis:objectId WHERE d.cmis:name LIKE ? ORDER BY d.cmis:name,s.SecondaryIntegerProp
* </pre>
*
* @param selectPropertyIds
* the property IDs in the SELECT statement, if {@code null} all
* properties are selected
* @param fromTypes
* a Map of type aliases (keys) and type IDs (values), the Map
* must contain exactly one primary type and zero or more
* secondary types
* @param whereClause
* an optional WHERE clause with placeholders ('?'), see
* {@link QueryStatement} for details
* @param orderByPropertyIds
* an optional list of properties IDs for the ORDER BY clause
*
* @return a new query statement object
*
* @see QueryStatement
*
* @cmis 1.0
*/
QueryStatement createQueryStatement(Collection<String> selectPropertyIds, Map<String, String> fromTypes,
String whereClause, List<String> orderByPropertyIds);
/**
* Returns the content changes.
*
* @param changeLogToken
* the change log token to start from or {@code null} to start
* from the first available event in the repository
* @param includeProperties
* indicates whether changed properties should be included in the
* result or not
* @param maxNumItems
* maximum numbers of events
*
* @return the change events
*
* @cmis 1.0
*/
ChangeEvents getContentChanges(String changeLogToken, boolean includeProperties, long maxNumItems);
/**
* Returns the content changes.
*
* @param changeLogToken
* the change log token to start from or {@code null} to start
* from the first available event in the repository
* @param includeProperties
* indicates whether changed properties should be included in the
* result or not
* @param maxNumItems
* maximum numbers of events
* @param context
* the OperationContext
*
* @return the change events
*
* @cmis 1.0
*/
ChangeEvents getContentChanges(String changeLogToken, boolean includeProperties, long maxNumItems,
OperationContext context);
/**
* Returns an iterator of content changes, starting from the given change
* log token to the latest entry in the change log.
* <p>
* Note: Paging and skipping are not supported.
*
* @param changeLogToken
* the change log token to start from or {@code null} to start
* from the first available event in the repository
* @param includeProperties
* indicates whether changed properties should be included in the
* result or not
*
* @cmis 1.0
*/
ItemIterable<ChangeEvent> getContentChanges(String changeLogToken, boolean includeProperties);
/**
* Returns an iterator of content changes, starting from the given change
* log token to the latest entry in the change log.
* <p>
* Note: Paging and skipping are not supported.
*
* @param changeLogToken
* the change log token to start from or {@code null} to start
* from the first available event in the repository
* @param includeProperties
* indicates whether changed properties should be included in the
* result or not
* @param context
* the OperationContext
*
* @cmis 1.0
*/
ItemIterable<ChangeEvent> getContentChanges(final String changeLogToken, final boolean includeProperties,
OperationContext context);
/**
* Returns the latest change log token.
* <p>
* In contrast to the repository info, this change log token is not cached.
* This method requests the token from the repository every single time it
* is called.
*
* @return the latest change log token or {@code null} if the repository
* doesn't provide one
*
* @cmis 1.0
*/
String getLatestChangeLogToken();
// create
/**
* Creates a new document.
*
* The stream in {@code contentStream} is consumed but not closed by this
* method.
*
* @return the object ID of the new document
*
* @see Folder#createDocument(Map, ContentStream, VersioningState, List,
* List, List, OperationContext)
*
* @cmis 1.0
*/
ObjectId createDocument(Map<String, ?> properties, ObjectId folderId, ContentStream contentStream,
VersioningState versioningState, List<Policy> policies, List<Ace> addAces, List<Ace> removeAces);
/**
* Creates a new document.
*
* The stream in {@code contentStream} is consumed but not closed by this
* method.
*
* @return the object ID of the new document
*
* @see Folder#createDocument(Map, ContentStream, VersioningState, List,
* List, List, OperationContext)
*
* @cmis 1.0
*/
ObjectId createDocument(Map<String, ?> properties, ObjectId folderId, ContentStream contentStream,
VersioningState versioningState);
/**
* Creates a new document from a source document.
*
* @return the object ID of the new document
*
* @see Folder#createDocumentFromSource(ObjectId, Map, VersioningState,
* List, List, List, OperationContext)
*
* @cmis 1.0
*/
ObjectId createDocumentFromSource(ObjectId source, Map<String, ?> properties, ObjectId folderId,
VersioningState versioningState, List<Policy> policies, List<Ace> addAces, List<Ace> removeAces);
/**
* Creates a new document from a source document.
*
* @return the object ID of the new document
*
* @see Folder#createDocumentFromSource(ObjectId, Map, VersioningState,
* List, List, List, OperationContext)
*
* @cmis 1.0
*/
ObjectId createDocumentFromSource(ObjectId source, Map<String, ?> properties, ObjectId folderId,
VersioningState versioningState);
/**
* Creates a new folder.
*
* @param properties
* the folder properties
* @param folderId
* the folder ID of the parent folder, not {@code null}
*
* @return the object ID of the new folder
*
* @see Folder#createFolder(Map, List, List, List, OperationContext)
*
* @cmis 1.0
*/
ObjectId createFolder(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, List<Ace> addAces,
List<Ace> removeAces);
/**
* Creates a new folder.
*
* @param properties
* the folder properties
* @param folderId
* the folder ID of the parent folder, not {@code null}
*
* @return the object ID of the new folder
*
* @see Folder#createFolder(Map, List, List, List, OperationContext)
*
* @cmis 1.0
*/
ObjectId createFolder(Map<String, ?> properties, ObjectId folderId);
/**
* Creates a folder path.
*
* All missing folders in the path are created. Existing folders are not
* touched.
*
* @param newPath
* the absolute path
* @param typeId
* the type ID of all folders that are being created
*
* @return the object ID of the deepest folder
*
* @cmis 1.0
*/
ObjectId createPath(String newPath, String typeId);
/**
* Creates a folder path.
*
* All missing folders in the path are created. Existing folders are not
* touched.
*
* @param startFolderId
* the ID of a folder in the path that the path creation should
* start with, {@code null} for the root folder.
* @param newPath
* the absolute path
* @param typeId
* the type ID of all folders that are being created
*
* @return the object ID of the deepest folder
*
* @cmis 1.0
*/
ObjectId createPath(ObjectId startFolderId, String newPath, String typeId);
/**
* Creates a folder path.
*
* All missing folders in the path are created. Existing folders are not
* touched.
*
* @param newPath
* the absolute path
* @param properties
* the properties of all folders that are being created
*
* @return the object ID of the deepest folder
*
* @cmis 1.0
*/
ObjectId createPath(String newPath, Map<String, ?> properties);
/**
* Creates a folder path.
*
* All missing folders in the path are created. Existing folders are not
* touched.
*
* @param startFolderId
* the ID of a folder in the path that the path creation should
* start with, {@code null} for the root folder
* @param newPath
* the absolute path
* @param properties
* the properties of all folders that are being created
*
* @return the object ID of the deepest folder
*
* @cmis 1.0
*/
ObjectId createPath(ObjectId startFolderId, String newPath, Map<String, ?> properties);
/**
* Creates a folder path.
*
* All missing folders in the path are created. Existing folders are not
* touched.
*
* @param startFolderId
* the ID of a folder in the path that the path creation should
* start with, {@code null} for the root folder
* @param newPath
* the absolute path
* @param properties
* the properties of all folders that are being created
*
* @return the object ID of the deepest folder
*
* @cmis 1.0
*/
ObjectId createPath(ObjectId startFolderId, String newPath, Map<String, ?> properties, List<Policy> policies,
List<Ace> addAces, List<Ace> removeAces);
/**
* Creates a new policy.
*
* @param properties
* the policy properties
* @param folderId
* the folder ID of the parent folder, {@code null} for an
* unfiled policy
*
* @return the object ID of the new policy
*
* @see Folder#createPolicy(Map, List, List, List, OperationContext)
*
* @cmis 1.0
*/
ObjectId createPolicy(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, List<Ace> addAces,
List<Ace> removeAces);
/**
* Creates a new policy.
*
* @param properties
* the policy properties
* @param folderId
* the folder ID of the parent folder, {@code null} for an
* unfiled policy
*
* @return the object ID of the new policy
*
* @see Folder#createPolicy(Map, List, List, List, OperationContext)
*
* @cmis 1.0
*/
ObjectId createPolicy(Map<String, ?> properties, ObjectId folderId);
/**
* Creates a new item.
*
* @param properties
* the item properties
* @param folderId
* the folder ID of the parent folder, {@code null} for an
* unfiled item
*
* @return the object ID of the new policy
*
* @see Folder#createItem(Map, List, List, List, OperationContext)
*
* @cmis 1.1
*/
ObjectId createItem(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, List<Ace> addAces,
List<Ace> removeAces);
/**
* Creates a new item.
*
* @param properties
* the item properties
* @param folderId
* the folder ID of the parent folder, {@code null} for an
* unfiled item
*
* @return the object ID of the new item
*
* @see Folder#createItem(Map, List, List, List, OperationContext)
*
* @cmis 1.1
*/
ObjectId createItem(Map<String, ?> properties, ObjectId folderId);
/**
* Creates a new relationship.
*
* @param properties
* the relationship properties
*
* @return the object ID of the new relationship
*
* @cmis 1.0
*/
ObjectId createRelationship(Map<String, ?> properties, List<Policy> policies, List<Ace> addAces,
List<Ace> removeAces);
/**
* Creates a new relationship.
*
* @param properties
* the relationship properties
*
* @return the object ID of the new relationship
*
* @cmis 1.0
*/
ObjectId createRelationship(Map<String, ?> properties);
/**
* Fetches the relationships from or to an object from the repository.
*
* @cmis 1.0
*/
ItemIterable<Relationship> getRelationships(ObjectId objectId, boolean includeSubRelationshipTypes,
RelationshipDirection relationshipDirection, ObjectType type, OperationContext context);
/**
* Updates multiple objects in one request.
*
* @cmis 1.0
*/
List<BulkUpdateObjectIdAndChangeToken> bulkUpdateProperties(List<CmisObject> objects, Map<String, ?> properties,
List<String> addSecondaryTypeIds, List<String> removeSecondaryTypeIds);
/**
* Deletes an object and, if it is a document, all versions in the version
* series.
*
* @param objectId
* the ID of the object
*
* @cmis 1.0
*/
void delete(ObjectId objectId);
/**
* Deletes an object.
*
* @param objectId
* the ID of the object
* @param allVersions
* if this object is a document this parameter defines if only
* this version or all versions should be deleted
*
* @cmis 1.0
*/
void delete(ObjectId objectId, boolean allVersions);
/**
* Deletes an object by path and, if it is a document, all versions in the
* version series.
*
* @param path
* the path of the object
*
* @cmis 1.0
*/
public void deleteByPath(String path);
/**
* Deletes an object by path and, if it is a document, all versions in the
* version series.
*
* @param parentPath
* the path of the parent folder
* @param name
* the (path segment) name of the object in the folder
*
* @cmis 1.0
*/
void deleteByPath(String parentPath, String name);
/**
* Deletes an object by path.
*
* @param path
* the path of the object
* @param allVersions
* if this object is a document this parameter defines if only
* this version or all versions should be deleted
*
* @cmis 1.0
*/
void deleteByPath(String path, boolean allVersions);
/**
* Deletes a folder and all subfolders.
*
* @param folderId
* the ID of the folder
* @param allVersions
* if this object is a document this parameter defines if only
* this version or all versions should be deleted
* @param unfile
* defines how objects should be unfiled
* @param continueOnFailure
* if {@code true} the repository tries to delete as many objects
* as possible; if {@code false} the repository stops at the
* first object that could not be deleted
*
* @return a list of object IDs which failed to be deleted
*
* @cmis 1.0
*/
List<String> deleteTree(ObjectId folderId, boolean allVersions, UnfileObject unfile, boolean continueOnFailure);
/**
* Deletes a folder and all subfolders by path.
*
* @param parentPath
* the path of the parent folder
* @param name
* the (path segment) name of the folder in the parent folder
* @param allVersions
* if this object is a document this parameter defines if only
* this version or all versions should be deleted
* @param unfile
* defines how objects should be unfiled
* @param continueOnFailure
* if {@code true} the repository tries to delete as many objects
* as possible; if {@code false} the repository stops at the
* first object that could not be deleted
*
* @return a list of object IDs which failed to be deleted
*
* @cmis 1.0
*/
List<String> deleteTreebyPath(String parentPath, String name, boolean allVersions, UnfileObject unfile,
boolean continueOnFailure);
/**
* Deletes a folder and all subfolders by path.
*
* @param path
* the path of the folder
* @param allVersions
* if this object is a document this parameter defines if only
* this version or all versions should be deleted
* @param unfile
* defines how objects should be unfiled
* @param continueOnFailure
* if {@code true} the repository tries to delete as many objects
* as possible; if {@code false} the repository stops at the
* first object that could not be deleted
*
* @return a list of object IDs which failed to be deleted
*
* @cmis 1.0
*/
List<String> deleteTreebyPath(String path, boolean allVersions, UnfileObject unfile, boolean continueOnFailure);
/**
* Retrieves the main content stream of a document.
*
* @param docId
* the ID of the document
*
* @return the content stream or {@code null} if the document has no content
* stream
*
* @cmis 1.0
*/
ContentStream getContentStream(ObjectId docId);
/**
* Retrieves the content stream of a document.
*
* @param docId
* the ID of the document
* @param streamId
* the stream ID or {@code null} for the main stream
* @param offset
* the offset of the stream or {@code null} to read the stream
* from the beginning
* @param length
* the maximum length of the stream or {@code null} to read to
* the end of the stream
*
* @return the content stream or {@code null} if the document has no content
* stream
*
* @cmis 1.0
*/
ContentStream getContentStream(ObjectId docId, String streamId, BigInteger offset, BigInteger length);
/**
* Retrieves the main content stream of a document.
*
* @param path
* the path of the document
*
* @return the content stream or {@code null} if the document has no content
* stream
*
* @cmis 1.0
*/
ContentStream getContentStreamByPath(String path);
/**
* Retrieves the content stream of a document.
*
* @param path
* the path of the document
* @param streamId
* the stream ID or {@code null} for the main stream
* @param offset
* the offset of the stream or {@code null} to read the stream
* from the beginning
* @param length
* the maximum length of the stream or {@code null} to read to
* the end of the stream
*
* @return the content stream or {@code null} if the document has no content
* stream
*
* @cmis 1.0
*/
ContentStream getContentStreamByPath(String path, String streamId, BigInteger offset, BigInteger length);
/**
* Fetches the ACL of an object from the repository.
*
* @param objectId
* the ID the object
* @param onlyBasicPermissions
* if {@code true} the repository should express the ACL only
* with the basic permissions defined in the CMIS specification;
* if {@code false} the repository can express the ACL with basic
* and repository specific permissions
*
* @return the ACL of the object
*
* @cmis 1.0
*/
Acl getAcl(ObjectId objectId, boolean onlyBasicPermissions);
/**
* Applies ACL changes to an object and dependent objects.
*
* Only direct ACEs can be added and removed.
*
* @param objectId
* the ID the object
* @param addAces
* list of ACEs to be added or {@code null} if no ACEs should be
* added
* @param removeAces
* list of ACEs to be removed or {@code null} if no ACEs should
* be removed
* @param aclPropagation
* value that defines the propagation of the ACE changes;
* {@code null} is equal to
* {@link AclPropagation#REPOSITORYDETERMINED}
*
* @return the new ACL of the object
*
* @cmis 1.0
*/
Acl applyAcl(ObjectId objectId, List<Ace> addAces, List<Ace> removeAces, AclPropagation aclPropagation);
/**
* Removes the direct ACEs of an object and sets the provided ACEs.
*
* The changes are local to the given object and are not propagated to
* dependent objects.
*
* @param objectId
* the ID the object
* @param aces
* list of ACEs to be set
*
* @return the new ACL of the object
*
* @cmis 1.0
*/
Acl setAcl(ObjectId objectId, List<Ace> aces);
/**
* Applies a set of policies to an object.
*
* This operation is not atomic. If it fails some policies might already be
* applied.
*
* @param objectId
* the ID the object
* @param policyIds
* the IDs of the policies to be applied
*
* @cmis 1.0
*/
void applyPolicy(ObjectId objectId, ObjectId... policyIds);
/**
* Removes a set of policies from an object.
*
* This operation is not atomic. If it fails some policies might already be
* removed.
*
* @param objectId
* the ID the object
* @param policyIds
* the IDs of the policies to be removed
*
* @cmis 1.0
*/
void removePolicy(ObjectId objectId, ObjectId... policyIds);
}