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/05 11:43:26 UTC
svn commit: r792253 - in /websites/production/chemistry: ./
content/java/developing/guide.html
Author: fmui
Date: Tue Jul 5 09:43:26 2011
New Revision: 792253
Log:
OpenCMIS guide update
Modified:
websites/production/chemistry/ (props changed)
websites/production/chemistry/content/java/developing/guide.html
Propchange: websites/production/chemistry/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Tue Jul 5 09:43:26 2011
@@ -1 +1 @@
-/websites/staging/chemistry/trunk:785583-792249
+/websites/staging/chemistry/trunk:785583-792252
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 Tue Jul 5 09:43:26 2011
@@ -201,7 +201,7 @@ such as Web applications and phone apps.
<h3 id="assumptions">Assumptions</h3>
<p>The guide assumes you are using the Eclipse IDE for code development, and have Maven and SVN installed.</p>
<ul>
-<li>You can download and install Eclipse <a href="http://www.eclipse.org/downloads.html">here</a>.</li>
+<li>You can download and install Eclipse <a href="http://www.eclipse.org/downloads/">here</a>.</li>
<li>You can download and install Maven <a href="http://maven.apache.org/download.html">here</a>.</li>
<li>You can download and install SVN for your platform <a href="http://subversion.apache.org/packages.html">here</a>.</li>
</ul>
@@ -217,7 +217,7 @@ among document systems, publishers and r
It is available under the open source <a href="http://www.apache.org/licenses/">Apache License</a> from the
<a href="http://chemistry.apache.org/">Apache Chemistry project</a>.
The OpenCMIS Client API is a Java client-side library that implements the CMIS specification. You can see the Javadoc for the
-OpenCMIS Client API <a href="http://incubator.apache.org/chemistry/javadoc/org/apache/chemistry/opencmis/client/api/package-summary.html">here</a>.
+OpenCMIS Client API <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/package-summary.html">here</a>.
CMIS defines a domain model that describes a vendor-neutral ECM repository and its contents, a set of services to work with the
repository and its content, and a set of bindings which a client uses to access the services.</p>
<h4 id="the_cmis_domain_model">The CMIS Domain Model</h4>
@@ -267,7 +267,7 @@ The CMIS services are:-</p>
<p>How does an OpenCMIS client communicate over the wire with a CMIS service endpoint? A CMIS repository can communicate over two protocols,
SOAP and <a href="http://tools.ietf.org/html/rfc5023">AtomPub</a>, and provide two corresponding bindings, a web services binding, and an AtomPub binding. A CMIS service endpoint will
provide a URL for both types of binding, and in OpenCMIS you specify the binding type when calling the <code>getRepositories()</code> method on
-the <a href="http://incubator.apache.org/chemistry/javadoc/org/apache/chemistry/opencmis/client/api/SessionFactory.html"><code>SessionFactory</code></a> object.</p>
+the <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/SessionFactory.html"><code>SessionFactory</code></a> object.</p>
<h4 id="the_opencmis_workbench">The OpenCMIS Workbench</h4>
<p>The workbench is a GUI repository browser that lets you quickly view the contents of a repository, create documents and folders, look at metadata, and
perform queries. It's really useful for debugging your applications, and for quickly testing out queries before you commit them to code. You can
@@ -374,7 +374,7 @@ Note that:-</p>
<span class="n">parameter</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">SessionParameter</span><span class="o">.</span><span class="na">USER</span><span class="o">,</span> <span class="s">"admin"</span><span class="o">);</span>
<span class="n">parameter</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">SessionParameter</span><span class="o">.</span><span class="na">PASSWORD</span><span class="o">,</span> <span class="s">"admin"</span><span class="o">);</span>
<span class="n">parameter</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">SessionParameter</span><span class="o">.</span><span class="na">ATOMPUB_URL</span><span class="o">,</span>
- <span class="s">"http://opencmis.cloudapp.net/inmemory/atom/"</span><span class="o">);</span>
+ <span class="s">"http://repo.opencmis.org/inmemory/atom/"</span><span class="o">);</span>
<span class="n">parameter</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">SessionParameter</span><span class="o">.</span><span class="na">BINDING_TYPE</span><span class="o">,</span> <span class="n">BindingType</span><span class="o">.</span><span class="na">ATOMPUB</span><span class="o">.</span><span class="na">value</span><span class="o">());</span>
</pre></div>
@@ -544,9 +544,9 @@ and a map of properties which define the
<p>Note the following points :-</p>
<ul>
<li>All paths start with the root folder <code>/</code>. </li>
-<li>The <a href="http://incubator.apache.org/chemistry/javadoc/org/apache/chemistry/opencmis/client/api/Document.html"><code>Document</code></a>
+<li>The <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/Document.html"><code>Document</code></a>
class does not have a <code>getPath()</code> method, since multifiling means a document can have more than one parent folder. It does implement the
-<code>getPaths()</code> method from the <a href="http://incubator.apache.org/chemistry/javadoc/org/apache/chemistry/opencmis/client/api/FileableCmisObject.html"><code>FileableCmisObject</code></a> interface.
+<code>getPaths()</code> method from the <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/FileableCmisObject.html"><code>FileableCmisObject</code></a> interface.
This returns a list of the current paths to the document object. </li>
</ul>
<h4 id="updating_a_document">Updating a document.</h4>
@@ -562,34 +562,42 @@ Note that the object ID returned when up
</pre></div>
-<p>You can update the contents of a document by setting a new <a href="http://incubator.apache.org/chemistry/javadoc/org/apache/chemistry/opencmis/commons/data/ContentStream.html">ContentStream</a>
+<p>You can update the contents of a document by setting a new <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/commons/data/ContentStream.html">ContentStream</a>
using the <code>setContentStream()</code> method.
You must set the overwrite flag if the document has existing content, otherwise an exception will be thrown. The following code snippet updated the content of the <code>test3.txt</code> document:-</p>
-<div class="codehilite"><pre><span class="n">content</span> <span class="o">=</span> <span class="s">"This is some updated test content for our renamed second document."</span><span class="o">;</span>
-<span class="n">buf</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">buf</span> <span class="o">=</span> <span class="n">content</span><span class="o">.</span><span class="na">getBytes</span><span class="o">(</span><span class="s">"UTF-8"</span><span class="o">);</span>
-<span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">UnsupportedEncodingException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
- <span class="n">e</span><span class="o">.</span><span class="na">printStackTrace</span><span class="o">();</span>
-<span class="o">}</span>
-<span class="n">input</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ByteArrayInputStream</span><span class="o">(</span><span class="n">buf</span><span class="o">);</span>
-<span class="n">contentStream</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">createContentStream</span><span class="o">(</span><span class="s">"test3.txt"</span><span class="o">,</span> <span class="n">buf</span><span class="o">.</span><span class="na">length</span><span class="o">,</span>
- <span class="n">mimetype</span><span class="o">,</span> <span class="n">input</span><span class="o">);</span>
-<span class="n">properties</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">Object</span><span class="o">>();</span>
-<span class="n">properties</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">properties</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">"test3.txt"</span><span class="o">);</span>
-<span class="n">doc2</span><span class="o">.</span><span class="na">setContentStream</span><span class="o">(</span><span class="n">contentStream</span><span class="o">,</span> <span class="kc">true</span><span class="o">);</span>
+<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">getContentStreamUpdatesCapability</span><span class="o">()</span>
+ <span class="o">.</span><span class="na">equals</span><span class="o">(</span><span class="n">CapabilityContentStreamUpdates</span><span class="o">.</span><span class="na">ANYTIME</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">"update without checkout not supported in this repository"</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">"updating content stream"</span><span class="o">);</span>
+ <span class="n">content</span> <span class="o">=</span> <span class="s">"This is some updated test content for our renamed second document."</span><span class="o">;</span>
+ <span class="n">buf</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">buf</span> <span class="o">=</span> <span class="n">content</span><span class="o">.</span><span class="na">getBytes</span><span class="o">(</span><span class="s">"UTF-8"</span><span class="o">);</span>
+ <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">UnsupportedEncodingException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">e</span><span class="o">.</span><span class="na">printStackTrace</span><span class="o">();</span>
+ <span class="o">}</span>
+ <span class="n">input</span> <span class="o">=</span> <span class="k">new</span> <span class="n">ByteArrayInputStream</span><span class="o">(</span><span class="n">buf</span><span class="o">);</span>
+ <span class="n">contentStream</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">createContentStream</span><span class="o">(</span><span class="s">"test3.txt"</span><span class="o">,</span> <span class="n">buf</span><span class="o">.</span><span class="na">length</span><span class="o">,</span>
+ <span class="n">mimetype</span><span class="o">,</span> <span class="n">input</span><span class="o">);</span>
+ <span class="n">properties</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">Object</span><span class="o">>();</span>
+ <span class="n">properties</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">properties</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">"test3.txt"</span><span class="o">);</span>
+ <span class="n">doc2</span><span class="o">.</span><span class="na">setContentStream</span><span class="o">(</span><span class="n">contentStream</span><span class="o">,</span> <span class="kc">true</span><span class="o">);</span>
-<span class="c1">// did it work?</span>
-<span class="k">try</span> <span class="o">{</span>
- <span class="n">content</span> <span class="o">=</span> <span class="n">getContentAsString</span><span class="o">(</span><span class="n">doc2</span><span class="o">.</span><span class="na">getContentStream</span><span class="o">());</span>
-<span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">IOException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
- <span class="n">e</span><span class="o">.</span><span class="na">printStackTrace</span><span class="o">();</span>
+ <span class="c1">// did it work?</span>
+ <span class="k">try</span> <span class="o">{</span>
+ <span class="n">content</span> <span class="o">=</span> <span class="n">getContentAsString</span><span class="o">(</span><span class="n">doc2</span><span class="o">.</span><span class="na">getContentStream</span><span class="o">());</span>
+ <span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="n">IOException</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
+ <span class="n">e</span><span class="o">.</span><span class="na">printStackTrace</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">"Contents of "</span> <span class="o">+</span> <span class="n">doc2</span><span class="o">.</span><span class="na">getName</span><span class="o">()</span> <span class="o">+</span> <span class="s">" are: "</span> <span class="o">+</span> <span class="n">content</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">"Contents of "</span> <span class="o">+</span> <span class="n">doc2</span><span class="o">.</span><span class="na">getName</span><span class="o">()</span> <span class="o">+</span> <span class="s">" are: "</span> <span class="o">+</span> <span class="n">content</span><span class="o">);</span>
</pre></div>
+<p>Note that this code snippet will not work for repositories that require a checkout to set a content stream.
+For more information on checkout see the <a href="#Versioning">versioning</a> section in this guide.</p>
<h4 id="deleting_a_document">Deleting a document</h4>
<p>You can delete any CMIS object using the <code>delete</code> method. The following code snippet lists the
contents of the test folder before and after a delete of one of the two documents
@@ -682,7 +690,7 @@ This code snippet uses a recursive metho
<p>Note the following points:-</p>
<ol>
-<li>The children of a <a href="http://incubator.apache.org/chemistry/javadoc/org/apache/chemistry/opencmis/client/api/Tree.html"><code>Tree</code></a> are themselves of type <code>Tree</code>. </li>
+<li>The children of a <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/Tree.html"><code>Tree</code></a> are themselves of type <code>Tree</code>. </li>
<li>The single argument of <code>getDescendants</code> is the depth or level of the tree that you want to go to. A depth of 1 will give you just the root of the tree.
A depth of -1 will return the full tree.</li>
</ol>
@@ -803,7 +811,7 @@ Getting immediate descendant types of CM
you are running this code against, there may be a number of children of the <code>Document</code> type, which are types derived from this base type.</p>
<h3 id="cmis_properties">CMIS Properties</h3>
<h4 id="displaying_the_properties_of_an_object">Displaying the properties of an Object</h4>
-<p>All objects of the CMIS base types implement the interface <a href="http://incubator.apache.org/chemistry/javadoc/org/apache/chemistry/opencmis/client/api/CmisObjectProperties.html"><code>CmisObjectProperties</code></a> which provides
+<p>All objects of the CMIS base types implement the interface <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/CmisObjectProperties.html"><code>CmisObjectProperties</code></a> which provides
accessors to CMIS object properties. The following code snippet uses the <code>getProperties()</code> method
to print out all the available properties on a newly created Document object, doc.</p>
<div class="codehilite"><pre> <span class="n">List</span><span class="o"><</span><span class="n">Property</span><span class="o"><?>></span> <span class="n">props</span> <span class="o">=</span> <span class="n">doc</span><span class="o">.</span><span class="na">getProperties</span><span class="o">();</span>
@@ -844,7 +852,7 @@ Last Modified Date=[Fri May 20 12:54:47
<h4 id="getting_a_property_explicitly">Getting a property explicitly</h4>
<p>Each object type has a known set of properties, and you can retrieve these explicitly.
-For example, the document type has a set of properties described by the <a href="http://incubator.apache.org/chemistry/javadoc/org/apache/chemistry/opencmis/client/api/DocumentProperties.html"><code>DocumentProperties</code></a> interface,
+For example, the document type has a set of properties described by the <a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/DocumentProperties.html"><code>DocumentProperties</code></a> interface,
and you can use the methods on this interface to retrieve
the value a property:-</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">"VersionLabel property on "</span> <span class="o">+</span> <span class="n">doc</span><span class="o">.</span><span class="na">getName</span><span class="o">()</span> <span class="o">+</span> <span class="s">" is "</span>
@@ -945,10 +953,10 @@ in this particular query. This code snip
<h3 id="exceptions">Exceptions</h3>
<p>If something goes wrong in an OpenCMIS method, an exception will be thrown.
All OpenCMIS exceptions extend
-<a href="http://incubator.apache.org/chemistry/javadoc/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html"><code>CmisBaseException</code></a>
+<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>
which is a Java runtime exception. Because all exceptions are runtime, you do not have to catch or specify the exceptions in your own code.
It does make sense to explicitly catch them in robust code. This code snippet forces an
-<a href="http://incubator.apache.org/chemistry/javadoc/org/apache/chemistry/opencmis/commons/exceptions/CmisInvalidArgumentException.html"><code>CmisInvalidArgumentException</code></a>
+<a href="http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/CmisInvalidArgumentException.html"><code>CmisInvalidArgumentException</code></a>
by supplying a null content stream.</p>
<div class="codehilite"><pre> <span class="k">try</span> <span class="o">{</span>
<span class="n">doc2</span><span class="o">.</span><span class="na">setContentStream</span><span class="o">(</span><span class="kc">null</span><span class="o">,</span> <span class="kc">false</span><span class="o">);</span>
@@ -962,14 +970,14 @@ by supplying a null content stream.</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://incubator.apache.org/chemistry/javadoc/org/apache/chemistry/opencmis/client/api/OperationContext.html"><code>OperationContext</code></a>.
+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>
<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>
-<div class="codehilite"><pre><span class="n">OperationContext</span> <span class="n">oc</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">createOperationContext</span><span class="o">();</span>
+<div class="codehilite"><pre><span class="n">OperationContext</span> <span class="n">operationContext</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">createOperationContext</span><span class="o">();</span>
<span class="n">oc</span><span class="o">.</span><span class="na">setCacheEnabled</span><span class="o">(</span><span class="kc">false</span><span class="o">);</span>
<span class="n">CmisObject</span> <span class="n">object</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">id</span><span class="o">,</span> <span class="n">oc</span><span class="o">);</span>
</pre></div>
@@ -986,7 +994,7 @@ or <code>getObjectByPath()</code> will n
return an empty list, even when there are renditions associated with the document object.
This is because renditions are not included in the default set of information.</p>
<p>You can use an <code>OperationContext</code> with a rendition filter to extend the information retrieved:-</p>
-<div class="codehilite"><pre> <span class="n">OperationContext</span> <span class="n">context</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">createOperationContext</span><span class="o">();</span>
+<div class="codehilite"><pre> <span class="n">OperationContext</span> <span class="n">operationContext</span> <span class="o">=</span> <span class="n">session</span><span class="o">.</span><span class="na">createOperationContext</span><span class="o">();</span>
<span class="n">context</span><span class="o">.</span><span class="na">setRenditionFilterString</span><span class="o">(</span><span class="s">"cmis:thumbnail"</span><span class="o">);</span>
<span class="n">CmisObject</span> <span class="n">oo</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">o</span><span class="o">.</span><span class="na">getId</span><span class="o">(),</span> <span class="n">context</span><span class="o">);</span>
<span class="n">List</span><span class="o"><</span><span class="n">Rendition</span><span class="o">></span> <span class="n">rl</span> <span class="o">=</span> <span class="n">oo</span><span class="o">.</span><span class="na">getRenditions</span><span class="o">();</span>
@@ -1162,6 +1170,8 @@ and the code checks for this.</p>
</pre></div>
+<p><a name="Versioning"></a> <br />
+</p>
<h3 id="versioning">Versioning</h3>
<p>Only document objects can be versioned.<br />
Whether or not a document object is versionable is specified by the <code>versionable</code> attribute on its Object-type.