| /* |
| * 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.OutputStream; |
| import java.math.BigInteger; |
| import java.util.List; |
| import java.util.Map; |
| import java.util.concurrent.Future; |
| |
| import org.apache.chemistry.opencmis.commons.data.Ace; |
| import org.apache.chemistry.opencmis.commons.data.Acl; |
| import org.apache.chemistry.opencmis.commons.data.ContentStream; |
| import org.apache.chemistry.opencmis.commons.definitions.TypeDefinition; |
| import org.apache.chemistry.opencmis.commons.enums.AclPropagation; |
| import org.apache.chemistry.opencmis.commons.enums.UnfileObject; |
| import org.apache.chemistry.opencmis.commons.enums.VersioningState; |
| import org.apache.chemistry.opencmis.commons.exceptions.CmisObjectNotFoundException; |
| |
| /** |
| * This interface provides asynchronous CMIS operations. |
| */ |
| public interface AsyncSession { |
| |
| /** |
| * Returns the session object. |
| * |
| * @return the session object, not {@code null} |
| */ |
| Session getSession(); |
| |
| // --- 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 |
| */ |
| Future<ObjectType> getTypeDefinition(String typeId); |
| |
| /** |
| * Creates a new type. |
| * |
| * @param type |
| * the type definition |
| * |
| * @return the new type definition |
| * |
| * @cmis 1.1 |
| */ |
| Future<ObjectType> createType(TypeDefinition type); |
| |
| /** |
| * Updates an existing type. |
| * |
| * @param type |
| * the type definition updates |
| * |
| * @return the updated type definition |
| * |
| * @cmis 1.1 |
| */ |
| Future<ObjectType> updateType(TypeDefinition type); |
| |
| /** |
| * Deletes a type. |
| * |
| * @param typeId |
| * the ID of the type to delete |
| * |
| * @cmis 1.1 |
| */ |
| Future<?> deleteType(String typeId); |
| |
| // --- objects --- |
| |
| /** |
| * 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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<CmisObject> getObjectByPath(String parentPath, String name, OperationContext context); |
| |
| /** |
| * Returns the latest version in a version series. |
| * |
| * @param objectId |
| * the document ID of an arbitrary version in the version series |
| * |
| * @return the latest document version |
| * |
| * @cmis 1.0 |
| */ |
| Future<Document> getLatestDocumentVersion(ObjectId objectId); |
| |
| /** |
| * Returns the latest version in a version series. |
| * |
| * @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 |
| */ |
| Future<Document> getLatestDocumentVersion(ObjectId objectId, OperationContext context); |
| |
| /** |
| * Returns the latest version in a version series. |
| * |
| * @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 |
| */ |
| Future<Document> getLatestDocumentVersion(ObjectId objectId, boolean major, OperationContext context); |
| |
| /** |
| * /** Returns the latest version in a version series. |
| * |
| * @param objectId |
| * the document ID of an arbitrary version in the version series |
| * |
| * @return the latest document version |
| * |
| * @cmis 1.0 |
| */ |
| Future<Document> getLatestDocumentVersion(String objectId); |
| |
| /** |
| * Returns the latest version in a version series. |
| * |
| * @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 |
| */ |
| Future<Document> getLatestDocumentVersion(String objectId, OperationContext context); |
| |
| /** |
| * Returns the latest version in a version series. |
| * |
| * @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 |
| */ |
| Future<Document> getLatestDocumentVersion(String objectId, boolean major, OperationContext context); |
| |
| // --- 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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<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 |
| * |
| * @cmis 1.0 |
| */ |
| Future<ObjectId> createDocumentFromSource(ObjectId source, Map<String, ?> properties, ObjectId folderId, |
| VersioningState versioningState); |
| |
| /** |
| * Creates a new folder. |
| * |
| * @return the object ID of the new folder |
| * |
| * @cmis 1.0 |
| */ |
| Future<ObjectId> createFolder(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, |
| List<Ace> addAces, List<Ace> removeAces); |
| |
| /** |
| * Creates a new folder. |
| * |
| * @return the object ID of the new folder |
| * |
| * @cmis 1.0 |
| */ |
| Future<ObjectId> createFolder(Map<String, ?> properties, ObjectId folderId); |
| |
| /** |
| * Creates a new policy. |
| * |
| * @return the object ID of the new policy |
| * |
| * @cmis 1.0 |
| */ |
| Future<ObjectId> createPolicy(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, |
| List<Ace> addAces, List<Ace> removeAces); |
| |
| /** |
| * Creates a new policy. |
| * |
| * @return the object ID of the new policy |
| * |
| * @cmis 1.0 |
| */ |
| Future<ObjectId> createPolicy(Map<String, ?> properties, ObjectId folderId); |
| |
| /** |
| * Creates a new item. |
| * |
| * @return the object ID of the new policy |
| * |
| * @cmis 1.1 |
| */ |
| Future<ObjectId> createItem(Map<String, ?> properties, ObjectId folderId, List<Policy> policies, List<Ace> addAces, |
| List<Ace> removeAces); |
| |
| /** |
| * Creates a new item. |
| * |
| * @return the object ID of the new item |
| * |
| * @cmis 1.1 |
| */ |
| Future<ObjectId> createItem(Map<String, ?> properties, ObjectId folderId); |
| |
| /** |
| * Creates a new relationship. |
| * |
| * @return the object ID of the new relationship |
| * |
| * @cmis 1.0 |
| */ |
| Future<ObjectId> createRelationship(Map<String, ?> properties, List<Policy> policies, List<Ace> addAces, |
| List<Ace> removeAces); |
| |
| /** |
| * Creates a new relationship. |
| * |
| * @return the object ID of the new relationship |
| * |
| * @cmis 1.0 |
| */ |
| Future<ObjectId> createRelationship(Map<String, ?> properties); |
| |
| // --- content --- |
| |
| /** |
| * Retrieves the content stream of a document. |
| * |
| * @param docId |
| * the ID of the document |
| * @param streamId |
| * the stream ID |
| * @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 |
| */ |
| Future<ContentStream> getContentStream(ObjectId docId, String streamId, BigInteger offset, BigInteger length); |
| |
| /** |
| * 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 |
| */ |
| Future<ContentStream> getContentStream(ObjectId docId); |
| |
| /** |
| * Reads the document content and writes it to an output stream. |
| * |
| * The output stream is not closed. |
| * |
| * @param docId |
| * the ID of the document |
| * @param streamId |
| * the stream ID |
| * @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 object (the input stream is closed) or |
| * {@code null} if the document has no content stream |
| * |
| * @cmis 1.0 |
| */ |
| Future<ContentStream> storeContentStream(ObjectId docId, String streamId, BigInteger offset, BigInteger length, |
| OutputStream target); |
| |
| /** |
| * Reads the document content and writes it to an output stream. |
| * |
| * The output stream is not closed. |
| * |
| * @param docId |
| * the ID of the document |
| * |
| * @return the content stream object (the input stream is closed) or |
| * {@code null} if the document has no content stream |
| * |
| * @cmis 1.0 |
| */ |
| Future<ContentStream> storeContentStream(ObjectId docId, OutputStream target); |
| |
| // --- delete --- |
| |
| /** |
| * 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 |
| */ |
| Future<?> delete(ObjectId objectId, boolean allVersions); |
| |
| /** |
| * 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 |
| */ |
| Future<?> delete(ObjectId objectId); |
| |
| /** |
| * 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 |
| */ |
| Future<List<String>> deleteTree(ObjectId folderId, boolean allVersions, UnfileObject unfile, |
| boolean continueOnFailure); |
| |
| // --- ACL --- |
| |
| /** |
| * 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 |
| */ |
| Future<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 |
| */ |
| Future<Acl> setAcl(ObjectId objectId, List<Ace> aces); |
| |
| // --- policy --- |
| |
| /** |
| * 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 |
| */ |
| Future<?> 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 |
| */ |
| Future<?> removePolicy(ObjectId objectId, ObjectId... policyIds); |
| } |