Understanding the Operation Context

The amount of metadata and associated information retrieved during an OpenCMIS or PortCMIS operation could be large, so certain methods return a sensible subset of the information by default, and provide additional methods that take an OperationContext. An OperationContext allows you to tune the amount of information returned by setting property filters, rendition filters, or by setting flags to include path segments, ACLs, Allowable Actions, Policies, and Relationships. The OperationContext is also used to control paging and caching in an operation.

Property Filter

Spec 2.2.1.2.1

The property filter defines which properties the repository must return. Only select the properties you really need to keep the transferred data as small as possible. The repository may return more properties than specified.

Query Names

The property filter is a collection of query names, not property IDs. The query names and property IDs of all properties defined in the CMIS specifation are same and therefore interchangeable. That might not be the case for custom types.

Minimal Property Filter

OpenCMIS and PortCMIS need at least the properties cmis:objectId, cmis:baseTypeId, and cmis:objectTypeId to create objects. The default operation context implementation adds these properties automatically if they are missing in the property filter.

OpenCMIS (Java)

OperationContext oc = ...
oc.setFilterString("cmis:objectId,cmis:name,cmis:createdBy");

PortCMIS (C#)

IOperationContext oc = ...
oc.FilterString = "cmis:objectId,cmis:name,cmis:createdBy";

Allowable Actions

Spec 2.2.1.2.6

Calculating the Allowable Actions of an object can be very expensive for a repository. Don’t request them if you don’t need them.

OpenCMIS (Java)

OperationContext oc = ...
oc.setIncludeAllowableActions(false); // don't request Allowable Actions

PortCMIS (C#)

IOperationContext oc = ...
oc.IncludeAllowableActions = false; // don't request Allowable Actions

ACLs

Spec 2.2.1.2.5

OpenCMIS (Java)

OperationContext oc = ...
oc.setIncludeAcls(true); // request ACLs

PortCMIS (C#)

IOperationContext oc = ...
oc.IncludeAcls = true; // request ACLs

Relationships

Spec 2.2.1.2.2

OpenCMIS (Java)

OperationContext oc = ...
oc.setIncludeRelationships(IncludeRelationships.BOTH); // request source and target relationships

PortCMIS (C#)

IOperationContext oc = ...
oc.IncludeRelationships = IncludeRelationships.Both; // request source and target relationships

Policies

Spec 2.2.1.2.3

OpenCMIS (Java)

OperationContext oc = ...
oc.setIncludePolicies(true); // request policies

PortCMIS (C#)

IOperationContext oc = ...
oc.IncludePolicies = true; // request policies

Rendition Filter

Spec 2.2.1.2.4

The rendition filter defines which rendition details should be returned by the repository. This filter is a comma separated list of rendition kinds (e.g. cmis:thumbnail) and MIME types.

OpenCMIS (Java)

OperationContext oc = ...
oc.setRenditionFilterString("cmis:thumbnail,image/*");

PortCMIS (C#)

IOperationContext oc = ...
oc.RenditionFilterString = "cmis:thumbnail,image/*";

Rendition filer examples:

* (include all renditions)
cmis:thumbnail (include only thumbnails)
image/* (include all image renditions)
application/pdf,application/x-shockwave-flash (include web ready renditions)
cmis:none (exclude all renditions)

Order By

Spec 2.2.1.2.7

The list of objects returned by getChildren, getCheckedOutDocs, and queryObjects can be ordered. This is a comma separated list of query names, followed by an optional ascending modifier “ASC” or descending modifier “DESC” for each query name. If the modifier is not stated, “ASC” is assumed.

Query Names

Similar to the property filter this is a collection of query names, not property IDs.

OpenCMIS (Java)

OperationContext oc = ...
oc.setOrderBy("cmis:createdBy DESC,cmis:name ASC");

PortCMIS (C#)

IOperationContext oc = ...
oc.OrderBy("cmis:createdBy DESC,cmis:name ASC");

List Batch Size

Lists returned by, for instances, getChildren and query are requested by OpenCMIS and PortCMIS in batches. The default batch size is 100. If a folder has 1,000 children, the client will make 10 getChildren calls to the server while looping over the children.

Optimal Batch Size

The optimal batch size depends on the use case. For applications that are using paging, the batch size should match the page size for the best performance. For applications that are processing all list items, the batch size should be as big as possible. The batch size maximum depends on the size of the list items (all items are loaded in main memory) and the server.

OpenCMIS (Java)

OperationContext oc = ...
oc.setMaxItemsPerPage(10000); // 10,000 items per batch

PortCMIS (C#)

IOperationContext oc = ...
oc.MaxItemsPerPage = 10000; // 10,000 items per batch

Caching

All objects retrieved by getObject and getObjectByPath are cached by default. If caching is turned off by an Operation Context, objects are not looked up in the cache and are not put into the cache. The methods getObject and getObjectByPath make a round-trip to the repository and get up-to-date data.

See also the section about the object cache.

OpenCMIS (Java)

OperationContext oc = ...
oc.setCacheEnabled(false); // no caching please

PortCMIS (C#)

IOperationContext oc = ...
oc.CacheEnabled = false; // no caching please

Creating Operation Context Objects

OpenCMIS (Java)

// create the default operation context
OperationContext oc1 = session.createOperationContext();

// create an operation context that selects nothing except the provided properties
OperationContext oc2 = OperationContextUtils.createMinimumOperationContext("cmis:objectId", "cmis:name", "cmis:createdBy");

// create an operation context that selects everything
OperationContext oc3 = OperationContextUtils.createMaximumOperationContext();

PortCMIS (C#)

// create the default operation context
IOperationContext oc1 = Session.CreateOperationContext();

// create an operation context that selects nothing except the provided properties
IOperationContext oc2 = OperationContextUtils.CreateMinimumOperationContext("cmis:objectId", "cmis:name", "cmis:createdBy");

// create an operation context that selects everything
IOperationContext oc3 = OperationContextUtils.CreateMaximumOperationContext();

Using an Operation Context

Many methods that retrieve objects or data accept an Operation Context object as an additional parameter. If no Operation Context object is provided, a default Operation Context object defines what should be requested.

OpenCMIS (Java)

OperationContext oc = ...

CmisObject cmisObject1 = session.getObject(id, oc);
CmisObject cmisObject2 = session.getObjectByPath(path, oc);
ItemIterable<CmisObject> children = folder.getChildren(oc);
List<Document> versions = doc.getAllVersions(oc);

PortCMIS (C#)

IOperationContext oc = ...

ICmisObject cmisObject1 = session.GetObject(id, oc);
ICmisObject cmisObject2 = session.GetObjectByPath(path, oc);
IItemEnumerable<ICmisObject> children = folder.GetChildren(oc);
IList<IDocument> versions = doc.GetAllVersions(oc);