You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@chemistry.apache.org by fm...@apache.org on 2011/07/22 17:30:14 UTC
svn commit: r793176 - in /websites/production/chemistry: ./
content/java/developing/guide.html
Author: fmui
Date: Fri Jul 22 15:30:13 2011
New Revision: 793176
Log:
Publishing merge to chemistry site by fmui
Modified:
websites/production/chemistry/ (props changed)
websites/production/chemistry/content/java/developing/guide.html
Propchange: websites/production/chemistry/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Fri Jul 22 15:30:13 2011
@@ -1 +1 @@
-/websites/staging/chemistry/trunk:785583-793107
+/websites/staging/chemistry/trunk:785583-793175
Modified: websites/production/chemistry/content/java/developing/guide.html
==============================================================================
--- websites/production/chemistry/content/java/developing/guide.html (original)
+++ websites/production/chemistry/content/java/developing/guide.html Fri Jul 22 15:30:13 2011
@@ -744,6 +744,8 @@ Folder ADGFolder122
<p>Note that <code>getDescendants</code> and <code>getFolderTree</code> are similar, but <code>getDescendants</code> finds objects of any fileable type, <code>getFolderTree</code> finds only folder
objects.</p>
+<p><a name="ObjectTypes"></a> <br />
+</p>
<h3 id="object_types">Object Types</h3>
<p>CMIS Objects have an object type. There are four base types, two of which <em>must</em> be supported by a repository </p>
<ul>
@@ -967,13 +969,66 @@ by supplying a null content stream.</p>
</pre></div>
+<p>If you are using the ATOMPUB binding, <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html"><code>CmisBaseException</code></a>
+provides a <code>getErrorContent()</code> method which returns the content of the error page returned from the server, if there is one. This can be extremely useful
+debugging, as the server side is normally able to provide far more information that the client. <br />
+In the following code snippet, a <code>CmisObjectNotFoundException</code> exception is forced by
+trying to create a document with an invalid type. The catch block prints the server's error page
+and the client stack trace.</p>
+<div class="codehilite"><pre> <span class="n">Folder</span> <span class="n">root</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">getRootFolder</span><span class="o">();</span>
+ <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">></span> <span class="n">newFolderProps</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">>();</span>
+ <span class="n">newFolderProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">OBJECT_TYPE_ID</span><span class="o">,</span> <span class="s">"cmis:folder"</span><span class="o">);</span>
+ <span class="n">newFolderProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">NAME</span><span class="o">,</span> <span class="s">"ADGFolderTest"</span><span class="o">);</span>
+ <span class="n">Folder</span> <span class="n">folderTest</span> <span class="o">=</span> <span class="n">root</span><span class="o">.</span><span class="na">createFolder</span><span class="o">(</span><span class="n">newFolderProps</span><span class="o">);</span>
+
+ <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">></span> <span class="n">newFileProps</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">>();</span>
+
+ <span class="n">newFileProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">OBJECT_TYPE_ID</span><span class="o">,</span> <span class="s">"cmis:badtype"</span><span class="o">);</span>
+ <span class="n">newFileProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">NAME</span><span class="o">,</span> <span class="s">"ADGFileTest"</span><span class="o">);</span>
+
+ <span class="k">try</span> <span class="o">{</span>
+ <span class="n">folderTest</span><span class="o">.</span><span class="na">createDocument</span><span class="o">(</span><span class="n">newFileProps</span><span class="o">,</span> <span class="kc">null</span><span class="o">,</span> <span class="n">VersioningState</span><span class="o">.</span><span class="na">MAJOR</span><span class="o">);</span>
+ <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">CmisObjectNotFoundException</span> <span class="n">e1</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">err</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"server error page :\n"</span> <span class="o">+</span> <span class="n">e1</span><span class="o">.</span><span class="na">getErrorContent</span><span class="o">());</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">err</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"\nClient stack trace :\n"</span><span class="o">);</span>
+ <span class="n">e1</span><span class="o">.</span><span class="na">printStackTrace</span><span class="o">();</span>
+ <span class="o">}</span>
+</pre></div>
+
+
+<p>The output from this snippet looks like this:-</p>
+<div class="codehilite"><pre>server error page :
+<html><head><title>Apache Chemistry OpenCMIS - objectNotFound error</title><style><!--H1 {font-size:24px;line-height:normal;font-weight:bold;background-color:#f0f0f0;color:#003366;border-bottom:1px solid #3c78b5;padding:2px;} BODY {font-family:Verdana,arial,sans-serif;color:black;font-size:14px;} HR {color:#3c78b5;height:1px;}--></style></head><body><h1>HTTP Status 404 - <!--exception-->objectNotFound<!--/exception--></h1><p><!--message-->unknown type id: cmis:badtype<!--/message--></p><hr noshade='noshade'/><!--stacktrace--><pre>
+org.apache.chemistry.opencmis.commons.exceptions.CmisObjectNotFoundException: unknown type id: cmis:badtype
+ at org.apache.chemistry.opencmis.inmemory.server.InMemoryRepositoryServiceImpl.getTypeDefinition(InMemoryRepositoryServiceImpl.java:110)
+ at org.apache.chemistry.opencmis.inmemory.server.InMemoryService.getTypeDefinition(InMemoryService.java:110)
+ ...
+ at org.apache.tomcat.util.net.AprEndpoint$Worker.run(AprEndpoint.java:1665)
+ at java.lang.Thread.run(Thread.java:662)
+
+</pre><!--/stacktrace--><hr noshade='noshade'/></body></html>
+
+Client stack trace :
+org.apache.chemistry.opencmis.commons.exceptions.CmisObjectNotFoundException: Not Found
+ at org.apache.chemistry.opencmis.client.bindings.spi.atompub.AbstractAtomPubService.convertStatusCode(AbstractAtomPubService.java:408)
+ at org.apache.chemistry.opencmis.client.bindings.spi.atompub.AbstractAtomPubService.read(AbstractAtomPubService.java:488)
+ ...
+ at org.apache.chemistry.opencmis.client.runtime.SessionImpl.createDocument(SessionImpl.java:651)
+ at org.apache.chemistry.opencmis.client.runtime.FolderImpl.createDocument(FolderImpl.java:87)
+ at org.apache.chemistry.opencmis.client.runtime.FolderImpl.createDocument(FolderImpl.java:409)
+ at org.apache.chemistry.opencmis.doc.TestingException.main(TestingException.java:104)
+</pre></div>
+
+
+<p><a name="OperationContext"></a><br />
+</p>
<h3 id="operation_context">Operation Context</h3>
<p>The amount of metadata and associated information retrieved during an OpenCMIS operation could be large,
so certain OpenCMIS methods return a sensible subset of the information by default,
and provide additional methods that take an <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/OperationContext.html"><code>OperationContext</code></a>.
-An OperationContext allows you to tune the amount of information returned by setting property filters, renditions filters, or by setting what. It is also used to control
-paging and caching in an operation. </p>
-<h4 id="setting">Setting</h4>
+An OperationContext allows you to tune the amount of information returned by setting property filters, renditions 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. </p>
<h4 id="caching">Caching</h4>
<p>Caching of objects is turned on by default in OpenCMIS, but if you want to guarantee that <code>getObject()</code>
or <code>getObjectByPath()</code> will not return stale objects, you can turn it off using an <code>OperationContext</code>:-</p>
@@ -1002,6 +1057,7 @@ This is because renditions are not inclu
<p>This code will retrieve any renditions of type <code>cmis:thumbnail</code> for this document object.</p>
+<p><a name="Paging"></a></p>
<h3 id="paging">Paging</h3>
<p>When you retrieve the children of a CMIS object, the result set returned is of an arbitrary size.
Retrieving a large result set synchronously could increase response times.
@@ -1023,18 +1079,18 @@ The <code>OperationContext</code> specif
<p>Note that <code>skipTo()</code> method returns a an iterable over the complete collection. The <code>getPage()</code> method is then be used to create an iterable over the page.</p>
<p>The following code snippet retrieves all objects in the result set, using the <code>getHasMoreItems()</code> method to end the <code>getPage()</code> loop.</p>
-<div class="codehilite"><pre> <span class="n">operationContext</span> <span class="o">=</span> <span class="k">new</span> <span class="n">OperationContextImpl</span><span class="o">();</span>
+<div class="codehilite"><pre> <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Getting complete result set in pages of 3"</span><span class="o">);</span>
+ <span class="n">operationContext</span> <span class="o">=</span> <span class="k">new</span> <span class="n">OperationContextImpl</span><span class="o">();</span>
<span class="n">operationContext</span><span class="o">.</span><span class="na">setMaxItemsPerPage</span><span class="o">(</span><span class="mi">3</span><span class="o">);</span>
<span class="n">children1</span> <span class="o">=</span> <span class="n">folderPaging</span><span class="o">.</span><span class="na">getChildren</span><span class="o">(</span><span class="n">operationContext</span><span class="o">);</span>
<span class="kt">int</span> <span class="n">pageNumber</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span>
<span class="kt">boolean</span> <span class="n">finished</span> <span class="o">=</span> <span class="kc">false</span><span class="o">;</span>
+ <span class="n">count</span><span class="o">=</span> <span class="mi">0</span><span class="o">;</span>
<span class="k">while</span> <span class="o">(!</span><span class="n">finished</span><span class="o">)</span> <span class="o">{</span>
- <span class="n">count</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span>
- <span class="n">ItemIterable</span><span class="o"><</span><span class="n">CmisObject</span><span class="o">></span> <span class="n">currentPage</span> <span class="o">=</span> <span class="n">children1</span><span class="o">.</span><span class="na">skipTo</span><span class="o">(</span>
- <span class="n">pageNumber</span> <span class="o">*</span> <span class="n">operationContext</span><span class="o">.</span><span class="na">getMaxItemsPerPage</span><span class="o">()).</span><span class="na">getPage</span><span class="o">();</span>
+ <span class="n">ItemIterable</span><span class="o"><</span><span class="n">CmisObject</span><span class="o">></span> <span class="n">currentPage</span> <span class="o">=</span> <span class="n">children1</span><span class="o">.</span><span class="na">skipTo</span><span class="o">(</span><span class="n">count</span><span class="o">).</span><span class="na">getPage</span><span class="o">();</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"page "</span> <span class="o">+</span> <span class="n">pageNumber</span> <span class="o">+</span> <span class="s">" has "</span> <span class="o">+</span> <span class="n">currentPage</span><span class="o">.</span><span class="na">getPageNumItems</span><span class="o">()</span> <span class="o">+</span> <span class="s">" items"</span><span class="o">);</span>
<span class="k">for</span> <span class="o">(</span><span class="n">CmisObject</span> <span class="n">item</span> <span class="o">:</span> <span class="n">currentPage</span><span class="o">)</span> <span class="o">{</span>
- <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"object "</span> <span class="o">+</span> <span class="n">count</span> <span class="o">+</span> <span class="s">" in page"</span> <span class="o">+</span> <span class="n">pageNumber</span> <span class="o">+</span> <span class="s">" is "</span>
- <span class="o">+</span> <span class="n">item</span><span class="o">.</span><span class="na">getName</span><span class="o">());</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"object "</span> <span class="o">+</span> <span class="n">count</span> <span class="o">+</span> <span class="s">" is "</span> <span class="o">+</span> <span class="n">item</span><span class="o">.</span><span class="na">getName</span><span class="o">());</span>
<span class="n">count</span><span class="o">++;</span>
<span class="o">}</span>
<span class="n">pageNumber</span><span class="o">++;</span>
@@ -1337,12 +1393,234 @@ to retrieve all renditions of a particul
</pre></div>
+<h3 id="advanced_use_of_types">Advanced use of types</h3>
+<p>Not all objects in a repository can be described by the basic CMIS types. A repository can
+define additional object-types that extend the CMIS base object-types. You can see the descendants of
+the cmis:document type in the output of code snippet in the <a href="#ObjectTypes">Object Types</a> section
+of this guide. Additional object types inherit the properties of the base type, and can define
+new custom properties. OpenCMIS does not allow you create objects with a custom type, but you can
+access existing objects of a custom type, and access the custom property values. The following
+code snippet searches for all objects in a repository of a particular custom type, and prints
+a some of each resulting object's custom properties. </p>
+<p>In this snippet the code looks for objects of type <code>ia:calendarEvent</code>, which is an Alfresco
+custom type, but you can alter the sample to access objects of a custom type within your repository.</p>
+<div class="codehilite"><pre><span class="k">if</span> <span class="o">(</span><span class="n">session</span><span class="o">.</span><span class="na">getRepositoryInfo</span><span class="o">().</span><span class="na">getCapabilities</span><span class="o">().</span><span class="na">getQueryCapability</span><span class="o">()</span>
+ <span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="n">CapabilityQuery</span><span class="o">.</span><span class="na">METADATAONLY</span><span class="o">))</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Full search not supported"</span><span class="o">);</span>
+<span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
+ <span class="n">String</span> <span class="n">query</span> <span class="o">=</span> <span class="s">"SELECT * FROM ia:calendarEvent"</span><span class="o">;</span>
+ <span class="n">ItemIterable</span><span class="o"><</span><span class="n">QueryResult</span><span class="o">></span> <span class="n">queryResult</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">query</span><span class="o">(</span><span class="n">query</span><span class="o">,</span> <span class="kc">false</span><span class="o">);</span>
+ <span class="k">for</span> <span class="o">(</span><span class="n">QueryResult</span> <span class="n">item</span> <span class="o">:</span> <span class="n">queryResult</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Found "</span>
+ <span class="o">+</span> <span class="n">item</span><span class="o">.</span><span class="na">getPropertyByQueryName</span><span class="o">(</span><span class="s">"cmis:name"</span><span class="o">).</span><span class="na">getFirstValue</span><span class="o">()</span> <span class="o">+</span> <span class="s">" of type "</span>
+ <span class="o">+</span> <span class="n">item</span><span class="o">.</span><span class="na">getPropertyByQueryName</span><span class="o">(</span><span class="s">"cmis:objectTypeId"</span><span class="o">).</span><span class="na">getFirstValue</span><span class="o">());</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"property ia:descriptionEvent is "</span>
+ <span class="o">+</span> <span class="n">item</span><span class="o">.</span><span class="na">getPropertyByQueryName</span><span class="o">(</span><span class="s">"ia:descriptionEvent"</span><span class="o">).</span><span class="na">getFirstValue</span><span class="o">());</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"property ia:toDate is "</span>
+ <span class="o">+</span> <span class="n">item</span><span class="o">.</span><span class="na">getPropertyByQueryName</span><span class="o">(</span><span class="s">"ia:toDate"</span><span class="o">).</span><span class="na">getFirstValue</span><span class="o">());</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"property ia:fromDate is "</span>
+ <span class="o">+</span> <span class="n">item</span><span class="o">.</span><span class="na">getPropertyByQueryName</span><span class="o">(</span><span class="s">"ia:fromDate"</span><span class="o">).</span><span class="na">getFirstValue</span><span class="o">());</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>The <a href="http://chemistry.apache.org/java/developing/tools/dev-tools-workbench.html">OpenCMIS Workbench</a> is a useful
+tool for examining the custom types defined in your repository. Just click on <strong>Types</strong> in the menu bar and expand the base-type
+tree. You can view all the properties of the type by clicking on its name.</p>
<h3 id="relationships">Relationships</h3>
-<img src="images/todo.gif" title="todo">
+<p>A Relationship Object a relationship between a source object and a target object. The relationship has direction, from source to target.
+It is non-invasive, in that a relationship does not modify either the source or the target object.
+A relationship object has a type, like any other CMIS object.
+The source and target objects must be independent objects, such as a document, folder, or policy objects.
+A relationship object does not have a content-stream, and is not versionable, queryable, or fileable.</p>
+<p>A repository does not have to support relationships.
+If it doesn't the relationship base object-type will not be returned by a "get types" call.</p>
+<p>Explicit relationships can be used to create an arbitrary relationship graph among independent objects.
+Such a relationship graph is only structural in nature.
+No inheritance or transitive properties are attached to a relationship graph.</p>
+<p>The following code snippet creates a relationship between 2 objects. Note that the Apache Chemistry in-memory
+repository does not support relationship objects, so this code expects to run against an Alfresco repository. This repository supports relationships,
+but the base type <code>cmis:relationship</code> is not defined as creatable, so the snippet uses an existing type <code>R:cmiscustom:assoc</code> which is
+a creatable sub-type of <code>cmis:relationship</code>. You can
+change this code to create a relationship of a type supported by your repository, between two objects of types supported by the
+relationship type. </p>
+<div class="codehilite"><pre> <span class="c1">// Check if the repo supports relationships</span>
+ <span class="n">ObjectType</span> <span class="n">relationshipType</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span>
+ <span class="k">try</span> <span class="o">{</span>
+ <span class="n">relationshipType</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">getTypeDefinition</span><span class="o">(</span><span class="s">"cmis:relationship"</span><span class="o">);</span>
+ <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">CmisObjectNotFoundException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">relationshipType</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span>
+ <span class="o">}</span>
-<h3 id="permissions">Permissions</h3>
-<img src="images/todo.gif" title="todo">
+ <span class="k">if</span> <span class="o">(</span><span class="n">relationshipType</span> <span class="o">==</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Repository does not support cmis:relationship objects"</span><span class="o">);</span>
+ <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
+ <span class="n">ObjectType</span> <span class="n">cmiscustomRelationshipType</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span>
+ <span class="k">try</span> <span class="o">{</span>
+ <span class="n">cmiscustomRelationshipType</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">getTypeDefinition</span><span class="o">(</span><span class="s">"R:cmiscustom:assoc"</span><span class="o">);</span>
+ <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">CmisObjectNotFoundException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">cmiscustomRelationshipType</span> <span class="o">=</span> <span class="kc">null</span><span class="o">;</span>
+ <span class="o">}</span>
+ <span class="k">if</span> <span class="o">(</span><span class="n">cmiscustomRelationshipType</span> <span class="o">==</span> <span class="kc">null</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Repository does not support R:cmiscustom:assoc objects"</span><span class="o">);</span>
+ <span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
+
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Creating folders for relationships example"</span><span class="o">);</span>
+
+ <span class="n">newFolderProps</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">>();</span>
+ <span class="n">newFolderProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">OBJECT_TYPE_ID</span><span class="o">,</span> <span class="s">"cmis:folder"</span><span class="o">);</span>
+ <span class="n">newFolderProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">NAME</span><span class="o">,</span> <span class="s">"ADGFolderAssociations"</span><span class="o">);</span>
+ <span class="n">Folder</span> <span class="n">folderAssociations</span> <span class="o">=</span> <span class="n">root</span><span class="o">.</span><span class="na">createFolder</span><span class="o">(</span><span class="n">newFolderProps</span><span class="o">);</span>
+
+ <span class="n">newFileProps</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">>();</span>
+ <span class="n">newFileProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">OBJECT_TYPE_ID</span><span class="o">,</span> <span class="s">"D:cmiscustom:document"</span><span class="o">);</span>
+ <span class="n">newFileProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">NAME</span><span class="o">,</span> <span class="s">"ADGFileSource"</span><span class="o">);</span>
+ <span class="n">Document</span> <span class="n">sourceDoc</span> <span class="o">=</span> <span class="n">folderAssociations</span><span class="o">.</span><span class="na">createDocument</span><span class="o">(</span><span class="n">newFileProps</span><span class="o">,</span> <span class="kc">null</span><span class="o">,</span>
+ <span class="n">VersioningState</span><span class="o">.</span><span class="na">MAJOR</span><span class="o">);</span>
+ <span class="n">newFileProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">OBJECT_TYPE_ID</span><span class="o">,</span> <span class="s">"cmis:document"</span><span class="o">);</span>
+ <span class="n">newFileProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">NAME</span><span class="o">,</span> <span class="s">"ADGFileTarget"</span><span class="o">);</span>
+ <span class="n">Document</span> <span class="n">targetDoc</span> <span class="o">=</span> <span class="n">folderAssociations</span><span class="o">.</span><span class="na">createDocument</span><span class="o">(</span><span class="n">newFileProps</span><span class="o">,</span> <span class="kc">null</span><span class="o">,</span>
+ <span class="n">VersioningState</span><span class="o">.</span><span class="na">MAJOR</span><span class="o">);</span>
+
+ <span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">></span> <span class="n">relProps</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">>();</span>
+ <span class="n">relProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"cmis:sourceId"</span><span class="o">,</span> <span class="n">sourceDoc</span><span class="o">.</span><span class="na">getId</span><span class="o">());</span>
+ <span class="n">relProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"cmis:targetId"</span><span class="o">,</span> <span class="n">targetDoc</span><span class="o">.</span><span class="na">getId</span><span class="o">());</span>
+ <span class="n">relProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"cmis:objectTypeId"</span><span class="o">,</span> <span class="s">"R:cmiscustom:assoc"</span><span class="o">);</span>
+ <span class="n">ObjectId</span> <span class="n">relId</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">createRelationship</span><span class="o">(</span><span class="n">relProps</span><span class="o">,</span> <span class="kc">null</span><span class="o">,</span> <span class="kc">null</span><span class="o">,</span> <span class="kc">null</span><span class="o">);</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"created relationship"</span><span class="o">);</span>
+
+ <span class="o">}</span>
+ <span class="o">}</span>
+</pre></div>
+
+
+<p>Each relationship type defines allowed source and target object types. The following code finds the type
+of an existing relationship, and displays the lists of allowed source types, and allowed object types.<br />
+</p>
+<div class="codehilite"><pre> <span class="n">RelationshipType</span> <span class="n">relType</span> <span class="o">=</span> <span class="o">(</span><span class="n">RelationshipType</span><span class="o">)</span> <span class="n">relationship</span><span class="o">.</span><span class="na">getType</span><span class="o">();</span>
+
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">relType</span><span class="o">.</span><span class="na">getDisplayName</span><span class="o">()</span>
+ <span class="o">+</span> <span class="s">"has the following allowed source types:"</span><span class="o">);</span>
+ <span class="k">for</span> <span class="o">(</span><span class="n">ObjectType</span> <span class="n">objectType</span> <span class="o">:</span> <span class="n">relType</span><span class="o">.</span><span class="na">getAllowedSourceTypes</span><span class="o">())</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"\t"</span> <span class="o">+</span> <span class="n">objectType</span><span class="o">.</span><span class="na">getDisplayName</span><span class="o">());</span>
+ <span class="o">}</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">relType</span><span class="o">.</span><span class="na">getDisplayName</span><span class="o">()</span>
+ <span class="o">+</span> <span class="s">"has the following allowed target types:"</span><span class="o">);</span>
+ <span class="k">for</span> <span class="o">(</span><span class="n">ObjectType</span> <span class="n">objectType</span> <span class="o">:</span> <span class="n">relType</span><span class="o">.</span><span class="na">getAllowedTargetTypes</span><span class="o">())</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"\t"</span> <span class="o">+</span> <span class="n">objectType</span><span class="o">.</span><span class="na">getDisplayName</span><span class="o">());</span>
+ <span class="o">}</span>
+</pre></div>
+
+
+<h3 id="access_control">Access Control</h3>
+<p>Document or folder objects can have an access control list (ACL), which
+controls access to the object. Policy objects can also control access to a document or folder.<br />
+</p>
+<p>An ACL is a list of Access Control Entries (ACEs). An ACE grants one or
+more permissions to a principal. A principal is a user, group, role, or something similar.</p>
+<p>An ACE holds :-</p>
+<ul>
+<li>One String with the principalid</li>
+<li>One or more Strings with the names of the permissions.</li>
+<li>A boolean flag <code>direct</code>, which is <em>true</em> if the ACE is directly assigned to the object, or <em>false</em> if the ACE is somehow derived</li>
+</ul>
+<p>There are three basic permissions predefined by CMIS:</p>
+<ul>
+<li><code>cmis:read</code>: permission for reading properties and reading content</li>
+<li><code>cmis:write</code>: permission to write properties and the content of an object. A respository can defin the property to include <code>cmis:read</code></li>
+<li><code>cmis:all</code>: all the permissions of a repository. It includes all other basic CMIS permissions.</li>
+</ul>
+<p>How these basic permissions are mapped to allowable actions is repository specific.
+You can discover the repository semantics for basic permissions with regard to allowable actions by examining
+the mappings parameter returned by session method
+<a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/Session.html#getRepositoryInfo()"><code>getRepositoryInfo</code></a>.
+A repository can extend the basic permissions with its own repository-specific permissions. The folowing code snippet prints out the
+permissions available for a repository, and the mappings of allowable actions to repository permissions:-</p>
+<div class="codehilite"><pre><span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"getting ACL capabilities"</span><span class="o">);</span>
+<span class="n">AclCapabilities</span> <span class="n">aclCapabilities</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">getRepositoryInfo</span><span class="o">().</span><span class="na">getAclCapabilities</span><span class="o">();</span>
+
+<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Propogation for this repository is "</span> <span class="o">+</span> <span class="n">aclCapabilities</span><span class="o">.</span><span class="na">getAclPropagation</span><span class="o">().</span><span class="na">toString</span><span class="o">());</span>
+
+<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"permissions for this repository are: "</span><span class="o">);</span>
+<span class="k">for</span> <span class="o">(</span><span class="n">PermissionDefinition</span> <span class="n">definition</span> <span class="o">:</span> <span class="n">aclCapabilities</span><span class="o">.</span><span class="na">getPermissions</span><span class="o">())</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">definition</span><span class="o">.</span><span class="na">toString</span><span class="o">());</span>
+<span class="o">}</span>
+
+<span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"\npermission mappings for this repository are: "</span><span class="o">);</span>
+<span class="n">Map</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">PermissionMapping</span><span class="o">></span> <span class="n">repoMapping</span> <span class="o">=</span> <span class="n">aclCapabilities</span><span class="o">.</span><span class="na">getPermissionMapping</span><span class="o">();</span>
+<span class="k">for</span> <span class="o">(</span><span class="n">String</span> <span class="nl">key:</span> <span class="n">repoMapping</span><span class="o">.</span><span class="na">keySet</span><span class="o">())</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="n">key</span> <span class="o">+</span> <span class="s">" maps to "</span> <span class="o">+</span> <span class="n">repoMapping</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="n">key</span><span class="o">).</span><span class="na">getPermissions</span><span class="o">());</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>You can specify how a repository should handle non-direct ACEs when you create an ACL, by specifying one of the following acl propogation values:-</p>
+<ul>
+<li><code>OBJECTONLY</code>: apply ACEs to a document or folder, without changing the ACLs of other objects</li>
+<li><code>PROPAGATE</code>: apply ACEs to the given object and all inheriting objects</li>
+<li><code>REPOSITORYDETERMINED</code>: allow the repositoryto use its own method of computing how changing an ACL for an object influences the non-direct ACEs of other objects.</li>
+</ul>
+<p>The following code snippet creates a document object, and prints out the ACEs in the created document's
+ACL. It then creates a new ACL with one ACE, adds it to the document, retrieves the document again, and
+prints out the ACEs now present in the document's ACL :-</p>
+<div class="codehilite"><pre><span class="c1">// Check if the repo supports ACLs</span>
+<span class="k">if</span> <span class="o">(!</span><span class="n">session</span><span class="o">.</span><span class="na">getRepositoryInfo</span><span class="o">().</span><span class="na">getCapabilities</span><span class="o">().</span><span class="na">getAclCapability</span><span class="o">()</span>
+ <span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="n">CapabilityAcl</span><span class="o">.</span><span class="na">MANAGE</span><span class="o">))</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Repository does not allow ACL management"</span><span class="o">);</span>
+<span class="o">}</span> <span class="k">else</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Repository allows ACL management"</span><span class="o">);</span>
+
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Creating folders for permissions example"</span><span class="o">);</span>
+
+ <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">></span> <span class="n">newFolderProps</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">>();</span>
+ <span class="n">newFolderProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">OBJECT_TYPE_ID</span><span class="o">,</span> <span class="s">"cmis:folder"</span><span class="o">);</span>
+ <span class="n">newFolderProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">NAME</span><span class="o">,</span> <span class="s">"ADGFolderPermissions"</span><span class="o">);</span>
+ <span class="n">Folder</span> <span class="n">folderAssociations</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">getRootFolder</span><span class="o">().</span><span class="na">createFolder</span><span class="o">(</span><span class="n">newFolderProps</span><span class="o">);</span>
+
+ <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">></span> <span class="n">newFileProps</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o"><</span><span class="n">String</span><span class="o">,</span> <span class="n">String</span><span class="o">>();</span>
+ <span class="n">ContentStream</span> <span class="n">contentStream</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ContentStreamImpl</span><span class="o">(</span><span class="s">"permissions.txt"</span><span class="o">,</span> <span class="kc">null</span><span class="o">,</span>
+ <span class="s">"plain/text"</span><span class="o">,</span> <span class="k">new</span> <span class="n">ByteArrayInputStream</span><span class="o">(</span><span class="s">"some content"</span><span class="o">.</span><span class="na">getBytes</span><span class="o">()));</span>
+ <span class="n">newFileProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">OBJECT_TYPE_ID</span><span class="o">,</span> <span class="s">"cmis:document"</span><span class="o">);</span>
+ <span class="n">newFileProps</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">PropertyIds</span><span class="o">.</span><span class="na">NAME</span><span class="o">,</span> <span class="s">"ADGFilePermissions"</span><span class="o">);</span>
+ <span class="n">Document</span> <span class="n">testDoc</span> <span class="o">=</span> <span class="n">folderAssociations</span><span class="o">.</span><span class="na">createDocument</span><span class="o">(</span><span class="n">newFileProps</span><span class="o">,</span> <span class="n">contentStream</span><span class="o">,</span>
+ <span class="n">VersioningState</span><span class="o">.</span><span class="na">MAJOR</span><span class="o">);</span>
+
+ <span class="n">OperationContext</span> <span class="n">operationContext</span> <span class="o">=</span> <span class="k">new</span> <span class="n">OperationContextImpl</span><span class="o">();</span>
+ <span class="n">operationContext</span><span class="o">.</span><span class="na">setIncludeAcls</span><span class="o">(</span><span class="kc">true</span><span class="o">);</span>
+ <span class="n">testDoc</span> <span class="o">=</span> <span class="o">(</span><span class="n">Document</span><span class="o">)</span> <span class="n">session</span><span class="o">.</span><span class="na">getObject</span><span class="o">(</span><span class="n">testDoc</span><span class="o">,</span> <span class="n">operationContext</span><span class="o">);</span>
+
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"ACL before adding an ace..."</span><span class="o">);</span>
+ <span class="k">for</span> <span class="o">(</span><span class="n">Ace</span> <span class="n">ace</span> <span class="o">:</span> <span class="n">testDoc</span><span class="o">.</span><span class="na">getAcl</span><span class="o">().</span><span class="na">getAces</span><span class="o">())</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Found ace: "</span> <span class="o">+</span> <span class="n">ace</span><span class="o">.</span><span class="na">getPrincipalId</span><span class="o">()</span> <span class="o">+</span> <span class="s">" toString "</span><span class="o">+</span> <span class="n">ace</span><span class="o">.</span><span class="na">toString</span><span class="o">());</span>
+ <span class="o">}</span>
+
+ <span class="n">List</span><span class="o"><</span><span class="n">String</span><span class="o">></span> <span class="n">permissions</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ArrayList</span><span class="o"><</span><span class="n">String</span><span class="o">>();</span>
+ <span class="n">permissions</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="s">"cmis:write"</span><span class="o">);</span>
+ <span class="n">String</span> <span class="n">principal</span> <span class="o">=</span> <span class="s">"admin"</span><span class="o">;</span>
+ <span class="n">Ace</span> <span class="n">aceIn</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">getObjectFactory</span><span class="o">().</span><span class="na">createAce</span><span class="o">(</span><span class="n">principal</span><span class="o">,</span> <span class="n">permissions</span><span class="o">);</span>
+ <span class="n">List</span><span class="o"><</span><span class="n">Ace</span><span class="o">></span> <span class="n">aceListIn</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ArrayList</span><span class="o"><</span><span class="n">Ace</span><span class="o">>();</span>
+ <span class="n">aceListIn</span><span class="o">.</span><span class="na">add</span><span class="o">(</span><span class="n">aceIn</span><span class="o">);</span>
+ <span class="n">testDoc</span><span class="o">.</span><span class="na">addAcl</span><span class="o">(</span><span class="n">aceListIn</span><span class="o">,</span> <span class="n">AclPropagation</span><span class="o">.</span><span class="na">REPOSITORYDETERMINED</span><span class="o">);</span>
+ <span class="n">testDoc</span> <span class="o">=</span> <span class="o">(</span><span class="n">Document</span><span class="o">)</span> <span class="n">session</span><span class="o">.</span><span class="na">getObject</span><span class="o">(</span><span class="n">testDoc</span><span class="o">,</span> <span class="n">operationContext</span><span class="o">);</span>
+
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"ACL after adding an ace..."</span><span class="o">);</span>
+ <span class="k">for</span> <span class="o">(</span><span class="n">Ace</span> <span class="n">ace</span> <span class="o">:</span> <span class="n">testDoc</span><span class="o">.</span><span class="na">getAcl</span><span class="o">().</span><span class="na">getAces</span><span class="o">())</span> <span class="o">{</span>
+ <span class="n">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Found ace: "</span> <span class="o">+</span> <span class="n">ace</span><span class="o">.</span><span class="na">getPrincipalId</span><span class="o">()</span> <span class="o">+</span> <span class="s">" toString "</span><span class="o">+</span> <span class="n">ace</span><span class="o">.</span><span class="na">toString</span><span class="o">());</span>
+ <span class="o">}</span>
+<span class="o">}</span>
+</pre></div>
+
+
+<p>Note the following points :-</p>
+<ul>
+<li>OpenCMIS does not return ACLs by default when retrieving a CMIS object. You must provide
+an OperationContext on the method and set it to include ACLs.</li>
+<li>We have set the propogation to be <code>AclPropagation.REPOSITORYDETERMINED</code> which lets the
+repository determine how the permissions are set for inheriting objects. Since this object
+is a document, there are no inheriting objects.</li>
+</ul>
<h3 id="change_logs">Change logs</h3>
<img src="images/todo.gif" title="todo">
@@ -1350,10 +1628,22 @@ to retrieve all renditions of a particul
<img src="images/todo.gif" title="todo">
<h2 id="performance">Performance</h2>
-<img src="images/todo.gif" title="todo">
-
+<p>OpenCMIS provides a number of features which you can use to avoid potential performance problems.</p>
+<ul>
+<li>You can use <a href="#Paging">paging</a> to manage potentially large result sets.</li>
+<li>You can use an <a href="#OperationContext">OperationContext</a> to tailor the metdata you wish to retrieve for a CMIS
+object.</li>
+</ul>
<h2 id="troubleshooting">Troubleshooting</h2>
-<p><img src="images/todo.gif" title="todo">Common pitfalls</p></div>
+<ul>
+<li>When handling CMIS exceptions in a CMIS client which connects with the AtomPub binding, remember that <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html"><code>CmisBaseException</code></a>
+provides a <code>getErrorContent()</code> method which returns the content of the error page returned from the server, if there is one. This can be extremely useful
+debugging, as the server side is normally able to provide far more information that the client.</li>
+<li>When handling CMIS exceptions in a CMIS client which connects with the Web Services binding, <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html"><code>CmisBaseException</code></a>
+provides a <code>getCode()</code> method which returns the error code returned from the server, if there is one. </li>
+<li>If a <code>java.lang.NullPointerException</code> is thrown when you are trying to access properties of a CMIS object such as the list of ACLs, Renditions, relationships, or allowable actions, it is likely you have either omitted an
+<code>OperationContext</code> when getting the object, or you have not set the <code>OperationContext</code> properly.</li>
+</ul></div>
<!-- Content -->
</td>
</tr>