content: /*
   * 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.commons.spi;
  
  import java.math.BigInteger;
  import java.util.List;
  
  import org.apache.chemistry.opencmis.commons.data.Acl;
  import org.apache.chemistry.opencmis.commons.data.AllowableActions;
  import org.apache.chemistry.opencmis.commons.data.BulkUpdateObjectIdAndChangeToken;
  import org.apache.chemistry.opencmis.commons.data.ContentStream;
  import org.apache.chemistry.opencmis.commons.data.ExtensionsData;
  import org.apache.chemistry.opencmis.commons.data.FailedToDeleteData;
  import org.apache.chemistry.opencmis.commons.data.ObjectData;
  import org.apache.chemistry.opencmis.commons.data.Properties;
  import org.apache.chemistry.opencmis.commons.data.RenditionData;
  import org.apache.chemistry.opencmis.commons.enums.IncludeRelationships;
  import org.apache.chemistry.opencmis.commons.enums.UnfileObject;
  import org.apache.chemistry.opencmis.commons.enums.VersioningState;
  
  /**
   * Object Service interface.
   * 
   * <p>
   * <em>
   * See the CMIS 1.0 and CMIS 1.1 specifications for details on the operations, parameters,
   * exceptions and the domain model.
   * </em>
   * </p>
   */
  public interface ObjectService {
  
      /**
       * Creates a document object of the specified type (given by the
       * cmis:objectTypeId property) in the (optionally) specified location.
       * 
       * The stream in <code>contentStream</code> is consumed but not closed by
       * this method.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param properties
       *            the property values that must be applied to the newly created
       *            document object
       * @param folderId
       *            <em>(optional)</em> if specified, the identifier for the
       *            folder that must be the parent folder for the newly created
       *            document object
       * @param contentStream
       *            <em>(optional)</em> the content stream that must be stored for
       *            the newly created document object
       * @param versioningState
       *            <em>(optional)</em> specifies what the versioning state of the
       *            newly created object must be (default is
       *            {@link VersioningState#MAJOR})
       * @param policies
       *            <em>(optional)</em> a list of policy IDs that must be applied
       *            to the newly created document object
       * @param addAces
       *            <em>(optional)</em> a list of ACEs that must be added to the
       *            newly created document object, either using the ACL from
       *            {@code folderId} if specified, or being applied if no
       *            {@code folderId} is specified
       * @param removeAces
       *            <em>(optional)</em> a list of ACEs that must be removed from
       *            the newly created document object, either using the ACL from
       *            {@code folderId} if specified, or being ignored if no
       *            {@code folderId} is specified
       * @param extension
       *            extension data
       * @return the ID of the newly created document
       */
      String createDocument(String repositoryId, Properties properties, String folderId, ContentStream contentStream,
              VersioningState versioningState, List<String> policies, Acl addAces, Acl removeAces,
              ExtensionsData extension);
  
      /**
       * Creates a document object as a copy of the given source document in the
       * (optionally) specified location.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param sourceId
       *            the identifier for the source document
       * @param properties
       *            the property values that must be applied to the newly created
       *            document object
       * @param folderId
       *            <em>(optional)</em> if specified, the identifier for the
       *            folder that must be the parent folder for the newly created
       *            document object
       * @param versioningState
       *            <em>(optional)</em> specifies what the versioning state of the
       *            newly created object must be (default is
       *            {@link VersioningState#MAJOR})
       * @param policies
       *            <em>(optional)</em> a list of policy IDs that must be applied
       *            to the newly created document object
       * @param addAces
       *            <em>(optional)</em> a list of ACEs that must be added to the
       *            newly created document object, either using the ACL from
       *            {@code folderId} if specified, or being applied if no
       *            {@code folderId} is specified
       * @param removeAces
       *            <em>(optional)</em> a list of ACEs that must be removed from
       *            the newly created document object, either using the ACL from
       *            {@code folderId} if specified, or being ignored if no
       *            {@code folderId} is specified
       * @param extension
       *            extension data
       * @return the ID of the newly created document
       */
      String createDocumentFromSource(String repositoryId, String sourceId, Properties properties, String folderId,
              VersioningState versioningState, List<String> policies, Acl addAces, Acl removeAces,
              ExtensionsData extension);
  
      /**
       * Creates a folder object of the specified type (given by the
       * cmis:objectTypeId property) in the specified location.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param properties
       *            the property values that must be applied to the newly created
       *            folder object
       * @param folderId
       *            the identifier for the parent folder
       * @param policies
       *            <em>(optional)</em> a list of policy IDs that must be applied
       *            to the newly created folder object
       * @param addAces
       *            <em>(optional)</em> a list of ACEs that must be added to the
       *            newly created folder object, either using the ACL from
       *            {@code folderId} if specified, or being applied if no
       *            {@code folderId} is specified
       * @param removeAces
       *            <em>(optional)</em> a list of ACEs that must be removed from
       *            the newly created folder object, either using the ACL from
       *            {@code folderId} if specified, or being ignored if no
       *            {@code folderId} is specified
       * @param extension
       *            extension data
       * @return the ID of the newly created folder
       */
      String createFolder(String repositoryId, Properties properties, String folderId, List<String> policies,
              Acl addAces, Acl removeAces, ExtensionsData extension);
  
      /**
       * Creates a relationship object of the specified type (given by the
       * cmis:objectTypeId property).
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param properties
       *            the property values that must be applied to the newly created
       *            relationship object
       * @param policies
       *            <em>(optional)</em> a list of policy IDs that must be applied
       *            to the newly created relationship object
       * @param addAces
       *            <em>(optional)</em> a list of ACEs that must be added to the
       *            newly created relationship object, either using the ACL from
       *            {@code folderId} if specified, or being applied if no
       *            {@code folderId} is specified
       * @param removeAces
       *            <em>(optional)</em> a list of ACEs that must be removed from
       *            the newly created relationship object, either using the ACL
       *            from {@code folderId} if specified, or being ignored if no
       *            {@code folderId} is specified
       * @param extension
       *            extension data
       * @return the ID of the newly created relationship
       */
      String createRelationship(String repositoryId, Properties properties, List<String> policies, Acl addAces,
              Acl removeAces, ExtensionsData extension);
  
      /**
       * Creates a policy object of the specified type (given by the
       * cmis:objectTypeId property).
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param properties
       *            the property values that must be applied to the newly created
       *            policy object
       * @param folderId
       *            <em>(optional)</em> if specified, the identifier for the
       *            folder that must be the parent folder for the newly created
       *            policy object
       * @param policies
       *            <em>(optional)</em> a list of policy IDs that must be applied
       *            to the newly created policy object
       * @param addAces
       *            <em>(optional)</em> a list of ACEs that must be added to the
       *            newly created policy object, either using the ACL from
       *            {@code folderId} if specified, or being applied if no
       *            {@code folderId} is specified
       * @param removeAces
       *            <em>(optional)</em> a list of ACEs that must be removed from
       *            the newly created policy object, either using the ACL from
       *            {@code folderId} if specified, or being ignored if no
       *            {@code folderId} is specified
       * @param extension
       *            extension data
       * @return the ID of the newly created policy
       */
      String createPolicy(String repositoryId, Properties properties, String folderId, List<String> policies,
              Acl addAces, Acl removeAces, ExtensionsData extension);
  
      /**
       * Creates an item object of the specified type (given by the
       * cmis:objectTypeId property).
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param properties
       *            the property values that must be applied to the newly created
       *            policy object
       * @param folderId
       *            <em>(optional)</em> if specified, the identifier for the
       *            folder that must be the parent folder for the newly created
       *            policy object
       * @param policies
       *            <em>(optional)</em> a list of policy IDs that must be applied
       *            to the newly created policy object
       * @param addAces
       *            <em>(optional)</em> a list of ACEs that must be added to the
       *            newly created policy object, either using the ACL from
       *            {@code folderId} if specified, or being applied if no
       *            {@code folderId} is specified
       * @param removeAces
       *            <em>(optional)</em> a list of ACEs that must be removed from
       *            the newly created policy object, either using the ACL from
       *            {@code folderId} if specified, or being ignored if no
       *            {@code folderId} is specified
       * @param extension
       *            extension data
       * @return the ID of the newly created item
       */
      String createItem(String repositoryId, Properties properties, String folderId, List<String> policies, Acl addAces,
              Acl removeAces, ExtensionsData extension);
  
      /**
       * Gets the list of allowable actions for an object.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectId
       *            the identifier for the object
       * @param extension
       *            extension data
       * @return the allowable actions
       */
      AllowableActions getAllowableActions(String repositoryId, String objectId, ExtensionsData extension);
  
      /**
       * Gets the specified information for the object specified by id.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectId
       *            the identifier for the object
       * @param filter
       *            <em>(optional)</em> a comma-separated list of query names that
       *            defines which properties must be returned by the repository
       *            (default is repository specific)
       * @param includeAllowableActions
       *            <em>(optional)</em> if {@code true}, then the repository must
       *            return the allowable actions for the object (default is
       *            {@code false})
       * @param includeRelationships
       *            <em>(optional)</em> indicates what relationships in which the
       *            object participates must be returned (default is
       *            {@link IncludeRelationships#NONE})
       * @param renditionFilter
       *            <em>(optional)</em> indicates what set of renditions the
       *            repository must return whose kind matches this filter (default
       *            is <code>"cmis:none"</code>)
       * @param includePolicyIds
       *            <em>(optional)</em> if {@code true}, then the repository must
       *            return the policy ids for the object (default is {@code false}
       *            )
       * @param includeAcl
       *            <em>(optional)</em> if {@code true}, then the repository must
       *            return the ACL for the object (default is {@code false})
       * @param extension
       *            extension data
       * @return the object
       */
      ObjectData getObject(String repositoryId, String objectId, String filter, Boolean includeAllowableActions,
              IncludeRelationships includeRelationships, String renditionFilter, Boolean includePolicyIds,
              Boolean includeAcl, ExtensionsData extension);
  
      /**
       * Gets the list of properties for an object.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectId
       *            the identifier for the object
       * @param filter
       *            <em>(optional)</em> a comma-separated list of query names that
       *            defines which properties must be returned by the repository
       *            (default is repository specific)
       * @param extension
       *            extension data
       * @return the object properties
       */
      Properties getProperties(String repositoryId, String objectId, String filter, ExtensionsData extension);
  
      /**
       * Gets the list of associated renditions for the specified object. Only
       * rendition attributes are returned, not rendition stream.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectId
       *            the identifier for the object
       * @param renditionFilter
       *            <em>(optional)</em> indicates what set of renditions the
       *            repository must return whose kind matches this filter (default
       *            is <code>"cmis:none"</code>)
       * @param maxItems
       *            <em>(optional)</em> the maximum number of items to return in a
       *            response (default is repository specific)
       * @param skipCount
       *            <em>(optional)</em> number of potential results that the
       *            repository must skip/page over before returning any results
       *            (default is 0)
       * @param extension
       *            extension data
       * @return the list of renditions
       */
      List<RenditionData> getRenditions(String repositoryId, String objectId, String renditionFilter,
              BigInteger maxItems, BigInteger skipCount, ExtensionsData extension);
  
      /**
       * Gets the specified information for the object specified by path.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param path
       *            the path to the object
       * @param filter
       *            <em>(optional)</em> a comma-separated list of query names that
       *            defines which properties must be returned by the repository
       *            (default is repository specific)
       * @param includeAllowableActions
       *            <em>(optional)</em> if {@code true}, then the repository must
       *            return the allowable actions for the object (default is
       *            {@code false})
       * @param includeRelationships
       *            <em>(optional)</em> indicates what relationships in which the
       *            object participates must be returned (default is
       *            {@link IncludeRelationships#NONE})
       * @param renditionFilter
       *            <em>(optional)</em> indicates what set of renditions the
       *            repository must return whose kind matches this filter (default
       *            is <code>"cmis:none"</code>)
       * @param includePolicyIds
       *            <em>(optional)</em> if {@code true}, then the repository must
       *            return the policy ids for the object (default is {@code false}
       *            )
       * @param includeAcl
       *            <em>(optional)</em> if {@code true}, then the repository must
       *            return the ACL for the object (default is {@code false})
       * @param extension
       *            extension data
       * @return the object
       */
      ObjectData getObjectByPath(String repositoryId, String path, String filter, Boolean includeAllowableActions,
              IncludeRelationships includeRelationships, String renditionFilter, Boolean includePolicyIds,
              Boolean includeAcl, ExtensionsData extension);
  
      /**
       * Gets the content stream for the specified document object, or gets a
       * rendition stream for a specified rendition of a document or folder
       * object.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectId
       *            the identifier for the object
       * @param extension
       *            extension data
       * @return the content stream
       */
      ContentStream getContentStream(String repositoryId, String objectId, String streamId, BigInteger offset,
              BigInteger length, ExtensionsData extension);
  
      /**
       * Updates properties of the specified object.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectId
       *            the identifier for the object. The repository might return a
       *            different/new object id
       * @param changeToken
       *            <em>(optional)</em> the last change token of this object that
       *            the client received. The repository might return a new change
       *            token (default is {@code null})
       * @param properties
       *            the updated property values that must be applied to the object
       * @param extension
       *            extension data
       */
      void updateProperties(String repositoryId, Holder<String> objectId, Holder<String> changeToken,
              Properties properties, ExtensionsData extension);
  
      /**
       * Updates properties and secondary types of one or more objects.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectIdsAndChangeTokens
       *            the ids and change tokens of the objects to update
       * @param properties
       *            the properties to set
       * @param addSecondaryTypeIds
       *            the secondary types to apply
       * @param removeSecondaryTypeIds
       *            the secondary types to remove
       * @param extension
       *            extension data
       * @return the list of updated objects with their change tokens
       */
      List<BulkUpdateObjectIdAndChangeToken> bulkUpdateProperties(String repositoryId,
              List<BulkUpdateObjectIdAndChangeToken> objectIdsAndChangeTokens, Properties properties,
              List<String> addSecondaryTypeIds, List<String> removeSecondaryTypeIds, ExtensionsData extension);
  
      /**
       * Moves the specified file-able object from one folder to another.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectId
       *            the identifier for the object. The repository might return a
       *            different/new object id
       * @param targetFolderId
       *            the identifier for the target folder
       * @param sourceFolderId
       *            the identifier for the source folder
       * @param extension
       *            extension data
       */
      void moveObject(String repositoryId, Holder<String> objectId, String targetFolderId, String sourceFolderId,
              ExtensionsData extension);
  
      /**
       * Deletes the specified object.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectId
       *            the identifier for the object
       * @param allVersions
       *            <em>(optional)</em> If {@code true} then delete all versions
       *            of the document, otherwise delete only the document object
       *            specified (default is {@code true})
       * @param extension
       *            extension data
       */
      void deleteObject(String repositoryId, String objectId, Boolean allVersions, ExtensionsData extension);
  
      /**
       * Deletes the specified folder object and all of its child- and
       * descendant-objects.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param folderId
       *            the identifier for the folder
       * @param allVersions
       *            <em>(optional)</em> If {@code true} then delete all versions
       *            of the document, otherwise delete only the document object
       *            specified (default is {@code true})
       * @param unfileObjects
       *            <em>(optional)</em> defines how the repository must process
       *            file-able child- or descendant-objects (default is
       *            {@link UnfileObject#DELETE})
       * @param continueOnFailure
       *            <em>(optional)</em> If {@code true}, then the repository
       *            should continue attempting to perform this operation even if
       *            deletion of a child- or descendant-object in the specified
       *            folder cannot be deleted (default is {@code false})
       * @param extension
       *            extension data
       * @return a (possibly incomplete) collection of object IDs of objects that
       *         couldn't be deleted
       */
      FailedToDeleteData deleteTree(String repositoryId, String folderId, Boolean allVersions,
              UnfileObject unfileObjects, Boolean continueOnFailure, ExtensionsData extension);
  
      /**
       * Sets the content stream for the specified document object.
       * 
       * The stream in <code>contentStream</code> is consumed but not closed by
       * this method.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectId
       *            the identifier for the object. The repository might return a
       *            different/new object id
       * @param overwriteFlag
       *            <em>(optional)</em> If {@code true}, then the repository must
       *            replace the existing content stream for the object (if any)
       *            with the input content stream. If If {@code false}, then the
       *            repository must only set the input content stream for the
       *            object if the object currently does not have a content stream
       *            (default is {@code true})
       * @param changeToken
       *            <em>(optional)</em> the last change token of this object that
       *            the client received. The repository might return a new change
       *            token (default is {@code null})
       * @param contentStream
       *            the content stream
       * @param extension
       *            extension data
       */
      void setContentStream(String repositoryId, Holder<String> objectId, Boolean overwriteFlag,
              Holder<String> changeToken, ContentStream contentStream, ExtensionsData extension);
  
      /**
       * Deletes the content stream for the specified document object.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectId
       *            the identifier for the object. The repository might return a
       *            different/new object id
       * @param changeToken
       *            <em>(optional)</em> the last change token of this object that
       *            the client received. The repository might return a new change
       *            token (default is {@code null})
       * @param extension
       *            extension data
       */
      void deleteContentStream(String repositoryId, Holder<String> objectId, Holder<String> changeToken,
              ExtensionsData extension);
  
      /**
       * Appends the content stream to the content of the document.
       * 
       * @param repositoryId
       *            the identifier for the repository
       * @param objectId
       *            the identifier for the object. The repository might return a
       *            different/new object id
       * @param changeToken
       *            <em>(optional)</em> the last change token of this object that
       *            the client received. The repository might return a new change
       *            token (default is {@code null})
       * @param contentStream
       *            the content stream to append
       * @param isLastChunk
       *            indicates if this content stream is the last chunk
       * @param extension
       *            extension data
       */
      void appendContentStream(String repositoryId, Holder<String> objectId, Holder<String> changeToken,
              ContentStream contentStream, boolean isLastChunk, ExtensionsData extension);
  }
  