CMIS Services

In two previous blog posts, I discussed the CMIS Domain Model and the CMIS Query Language.  This post discusses the CMIS Services.  The CMIS Services expose methods by which a client can:

• Browse the repository
• Inspect objects in the repository
• Manipulate objects in the repository

The methods that are provided to the client are organized into 9 services.

• Repository Services
• Navigation Services
• Discovery Services
• Object Services
• Versioning Services
• Relationship Services
• Multi-filing Services
• Policy Services
• ACL Services

Calling the Methods

The CMIS Specification documents all of the methods on all of the services including:

• Mandatory Inputs
• Optional Inputs
• Outputs
• Exceptions thrown

Most of the methods share common elements many of them are itemized below.  One thing that worth noting is that since a CMIS Service Endpoint (the starting URL for a repository) can be shared by multiple repositories, the Repository ID is a mandatory input to all methods with the exception of the Get Repositories method.

Paging

Most methods that return a collection of objects allow the client to specify paging (maximum number of objects returned after skipping a specified number objects at the beginning of the result set). In the event that the client does not request paging, the repository has the option of paging the results.  If the results are paged, the repository must indicate whether or not there are more results and should return the total number of objects in the result set.

Change Tokens

CMIS compliant repositories may add a change log token property to objects.  If the repository adds this property, then the change log token must be provided by the client when an object is being updated.  This allows the repository to detect a situation when the client is attempting to update a stale copy of the object (i.e. client A has updated the object since that client B retrieved the copy of the object that it is trying to update).  In this case an Update Conflict Exception will be thrown.  This situation could occur in situations where objects can be updated without being checked out.

Controlling the Amount of Information Returned on Objects

The client can control the amount of information that the repository returns on each object.  The following optional parameters can be used to control that flow:

• An optional property filter can be used to specify the subset of properties that will be returned for each object.
• An optional input parameter specifies which relationships that an object is participating in should be returned. The values are (none, source, target, both).
• A boolean flag is used to determine whether or not the policies that are applied to the object are returned.
• An optional renditions filter is used to determine which renditions are returned.
• A boolean flag is used to determine whether or not the ACLs of an object are returned.
• A boolean flag is used to determine whether or not the Allowable Actions of an object are returned.

Exceptions

The CMIS specification defines a number of exceptions that can be thrown to indicate errors and/or unanticipated problems with the repository.  General exceptions are exceptions that can be thrown by any method; they are not generally listed for each method.  Specific exceptions are specific to a subset of methods and are generally included in the list of exceptions thrown for the methods that throw them.

General Exceptions

• Invalid Argument
  A required input parameter was not provided or an invalid input parameter was supplied.
• Object Not Found
  A non-existent object was specified.
• Not Supported
  Method requires an optional capability that is not supported.
• Permission Denied
  The user does not have permission to perform the operation.
• Runtime
  Catch all for none of the above.

Specific Exceptions

• Constraint
  The operation would violate some object or folder level constraint.
• Content Already Exists
  The client is trying to add (rather than overwrite) an content stream that exists.
• Filter Not Valid
  The filter specification provided is not valid.
• Name Constraint Violation
  The client is attempting to create an object with an invalid name.
• Storage
  The repository cannot store object because of storage issue (disk space etc...).
• Stream Not Supported
  The client is trying to manipulate a content stream on an object type that does not support content streams.
• Update Conflict
  The client is attempting to update an object that is no longer current (object may have been current but then due to the asynchronous nature of the system, the object is no longer current).
• Versioning
  The client is trying to perform an operation that can only be done on a current object on a non current object.

Overview of the Methods

Below is a list of all of the methods available to the client.  There is a brief summary of what functionality each method provides.  Keep in mind that some of these methods may not be supported in all repositories as they may provide optional functionality.

Browsing The Repository

Repository Services

• Get Repositories
  Get a list of repositories that can be accessed from this service endpoint.
• Get Repository Info
  Get information about the specified repository
• Get Type Children, Get Type Descendants
  Various ways to discover the object types in a repository
• Get Type Definition
  Get the definition (list of properties) of the specified type.

Navigation Services

• Get Folder Tree, Get Descendants, Get Children
  Retrieve descendant objects (each one has slightly different nuances).
• Get Folder Parent, Get Object Parents
  Retrieve an object's parent folder(s).
• Get Checkedout Docs
  Retrieve list of checked out documents.

Discovery Services

• Query
  Execute a CMIS query
• Get Content Changes
  Gets a list of changes to the repository.  The client can provide an optional change log token that would specify the first event to be included in the list.

Inspecting Objects

Object Services

• Get Object, Get Object By Path
  Retrieve objects
• Get Properties, Get Allowable Actions, Get Renditions
  Get information about objects
• Get Content Stream
  Retrieve an object's content stream.

Versioning Services

• Get Properties Of Latest Version, Get Object Of Latest Version
  Get information about latest version of object
• Get All Versions
  Retrieve an object's version history.

Relationship Services

• Get Object Relationships
  Get the relationships that an object is a part of

Policy Services

• Get Applied Policies
  Get the policies that are applied to an object

ACL Services

• Get ACL
  Get the permissions associated with an object

Manipulating Objects

Object Services

• Create Relationship, Create Document, Create Document From Source, Create Policy, Create Folder
  Create objects
• Update Properties, Move Object
  Update objects
• Delete Object, Delete Tree
  Remove objects
• Set Content Stream, Delete Content Stream
  Update content streams

Versioning Services

• Check Out, Check In, Cancel Check Out
  Control locking/unlocking of an object for the purpose of updating
• Delete All Versions
  Remove version history.

Milti-Filing Services

• Add Object To Folder, Remove Object From Folder
  File and un-file objects.  If Multi-filing is supported in the repository, then an object can be added to multiple folders. If un-filing is supported in the repository, then an object can be removed from all folders that it is filed in without deleting the object.

Policy Services

• Apply Policy, Remove Policy
  Apply and remove policies to/from an object

ACL Services

• Apply ACL
  Set the permissions associated with an object

Summary

As you can see the CMIS specification provided a comprehensive set of methods by which a client can interact with the repository.  In my next post, I will discuss the SOAP and REST bindings that are used to implement this functionality over the wire.