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 2013/03/04 16:13:17 UTC
svn commit: r1452343 -
/chemistry/site/trunk/content/java/developing/guide.mdtext
Author: fmui
Date: Mon Mar 4 15:13:17 2013
New Revision: 1452343
URL: http://svn.apache.org/r1452343
Log:
some developer guide corrections
Modified:
chemistry/site/trunk/content/java/developing/guide.mdtext
Modified: chemistry/site/trunk/content/java/developing/guide.mdtext
URL: http://svn.apache.org/viewvc/chemistry/site/trunk/content/java/developing/guide.mdtext?rev=1452343&r1=1452342&r2=1452343&view=diff
==============================================================================
--- chemistry/site/trunk/content/java/developing/guide.mdtext (original)
+++ chemistry/site/trunk/content/java/developing/guide.mdtext Mon Mar 4 15:13:17 2013
@@ -20,7 +20,7 @@ Notice: Licensed to the Apache Softwa
## Audience
This guide is for software engineers who want to use the Apache Chemistry OpenCMIS client to access CMIS-compliant
-content repositories from java code. The examples included in the guide assume the code is running in
+content repositories from Java code. The examples included in the guide assume the code is running in
a standalone Java application, but the OpenCMIS client can be used by on any Java platform,
such as Web applications and phone apps.
@@ -58,7 +58,7 @@ OpenCMIS is a collection of Java librari
It is available under the open source [Apache License](http://www.apache.org/licenses/) from the
[Apache Chemistry project](http://chemistry.apache.org/).
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 [here](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/package-summary.html).
+OpenCMIS Client API [here](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/package-summary.html).
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.
@@ -116,7 +116,7 @@ The CMIS services are:-
How does an OpenCMIS client communicate over the wire with a CMIS service endpoint? A CMIS repository can communicate over two protocols,
SOAP and [AtomPub](http://tools.ietf.org/html/rfc5023), 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 `getRepositories()` method on
-the [`SessionFactory`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/SessionFactory.html) object.
+the [`SessionFactory`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/SessionFactory.html) object.
#### The OpenCMIS Workbench
@@ -156,14 +156,14 @@ The simplest way to view the sample code
1. Add the maven repository to your eclipse workspace classpath with the following command. You only need to perform this step once.
- :::text
- mvn eclipse:configure-workspace -Declipse.workspace=<path-to-your-eclipse-workspace>
+ :::text
+ mvn eclipse:configure-workspace -Declipse.workspace=<path-to-your-eclipse-workspace>
-1. Create a an eclipse project from the code, and import it into your eclipse.
+1. Create an Eclipse project from the code, and import it into your eclipse.
Type the following command :-
- :::text
- mvn eclipse:eclipse
+ :::text
+ mvn eclipse:eclipse
1. Import the project into eclipse:-
@@ -185,8 +185,7 @@ This section introduces the most commonl
On a command line, type the following command :-
:::text
- svn co \
- https://svn.apache.org/repos/asf/chemistry/opencmis/trunk/chemistry-opencmis-samples/chemistry-opencmis-getting-started
+ svn co https://svn.apache.org/repos/asf/chemistry/opencmis/trunk/chemistry-opencmis-samples/chemistry-opencmis-getting-started
You can then build the sample and run the `org.apache.chemistry.opencmis.doc.GettingStarted` sample using maven, by typing the following command
@@ -220,23 +219,22 @@ Note that:-
1. This repository does not require credentials, but the code snippet sets a user id and password to show how this is done
1. The code uses the `ATOMPUB` binding for connection.
- :::java
- SessionFactory sessionFactory = SessionFactoryImpl.newInstance();
- Map<String, String> parameter = new HashMap<String, String>();
- parameter.put(SessionParameter.USER, "admin");
- parameter.put(SessionParameter.PASSWORD, "admin");
- parameter.put(SessionParameter.ATOMPUB_URL,
- "http://repo.opencmis.org/inmemory/atom/");
- parameter.put(SessionParameter.BINDING_TYPE, BindingType.ATOMPUB.value());
+ :::java
+ SessionFactory sessionFactory = SessionFactoryImpl.newInstance();
+ Map<String, String> parameter = new HashMap<String, String>();
+ parameter.put(SessionParameter.USER, "admin");
+ parameter.put(SessionParameter.PASSWORD, "admin");
+ parameter.put(SessionParameter.ATOMPUB_URL, "http://repo.opencmis.org/inmemory/atom/");
+ parameter.put(SessionParameter.BINDING_TYPE, BindingType.ATOMPUB.value());
#### Connecting to a repository by id
In a production environment, the client code will probably know the ID of the repository that it wants to connect to.
The following code snippet shows how to connect to a repository using its ID.
- :::java
- parameter.put(SessionParameter.REPOSITORY_ID, "A1");
- Session session = sessionFactory.createSession(parameter);
+ :::java
+ parameter.put(SessionParameter.REPOSITORY_ID, "A1");
+ Session session = sessionFactory.createSession(parameter);
That's it. Any work you want to do against the repository uses this session.
@@ -245,23 +243,21 @@ That's it. Any work you want to do again
The CMIS specification allows a CMIS service endpoint to advertise one or more repositories, so this code snippet retrieves a list of repositories. In this
case there the code chooses the first repository in list:-
- :::java
- List<Repository> repositories = new ArrayList<Repository>();
- repositories = sessionFactory.getRepositories(parameter);
- for (Repository r : repositories) {
- System.out.println("Found repository: " + r.getName());
- }
+ :::java
+ List<Repository> repositories = sessionFactory.getRepositories(parameter);
+ for (Repository r : repositories) {
+ System.out.println("Found repository: " + r.getName());
+ }
Now you can create your session with the first and only repository:-
- :::java
- Repository repository = repositories.get(0);
- parameter.put(SessionParameter.REPOSITORY_ID, repository.getId());
- Session session = sessionFactory.createSession(parameter);
-
- System.out.println("Got a connection to repository: "
- + repository.getName() + ", with id: "
- + repository.getId());
+ :::java
+ Repository repository = repositories.get(0);
+ Session session = repository.createSession();
+
+ System.out.println("Got a connection to repository: "
+ + repository.getName() + ", with id: "
+ + repository.getId());
That's it. Any work you want to do against the repository uses this session.
@@ -281,13 +277,14 @@ The Document is the only object that can
Now you have a session you can start examining the repository. All CMIS repositories have a root folder, which is the single top level folder in the hierarchy.
To list the objects in the root folder of your repository you use the `getRootFolder()` method on the session.
- :::java
- Folder root = session.getRootFolder();
- ItemIterable<CmisObject> children = root.getChildren();
- System.out.println("Found the following objects in the root folder:-");
- for (CmisObject o : children) {
- System.out.println(o.getName() + " which is of type " + o.getType().getDisplayName());
- }
+ :::java
+ Folder root = session.getRootFolder();
+ ItemIterable<CmisObject> children = root.getChildren();
+
+ System.out.println("Found the following objects in the root folder:-");
+ for (CmisObject o : children) {
+ System.out.println(o.getName() + " which is of type " + o.getType().getDisplayName());
+ }
#### Creating a folder object
@@ -295,58 +292,58 @@ To create a folder, you use the `create
As with most CMIS methods, it takes a map of properties which define the Object to be created.
In this code snippet a folder with the name `ADGNewFolder` is created in the root folder:-
- :::java
- System.out.println("Creating 'ADGNewFolder' in the root folder");
- Map<String, String> newFolderProps = new HashMap<String, String>();
- newFolderProps.put(PropertyIds.OBJECT_TYPE_ID, "cmis:folder");
- newFolderProps.put(PropertyIds.NAME, "ADGNewFolder");
- Folder newFolder = root.createFolder(newFolderProps);
-
- // Did it work?
- children = root.getChildren();
- System.out.println("Now finding the following objects in the root folder:-");
- for (CmisObject o : children) {
- System.out.println(o.getName());
- }
+ :::java
+ System.out.println("Creating 'ADGNewFolder' in the root folder");
+ Map<String, String> newFolderProps = new HashMap<String, String>();
+ newFolderProps.put(PropertyIds.OBJECT_TYPE_ID, "cmis:folder");
+ newFolderProps.put(PropertyIds.NAME, "ADGNewFolder");
+
+ Folder newFolder = root.createFolder(newFolderProps);
+
+ // Did it work?
+ ItemIterable<CmisObject> children = root.getChildren();
+ System.out.println("Now finding the following objects in the root folder:-");
+ for (CmisObject o : children) {
+ System.out.println(o.getName());
+ }
Note that the properties set for in the above code snippet are the minimum set of name and object type id.
There are many other properties you can set on creation, depending on the object type.
-#### Creating a a simple document object
+#### Creating a simple document object
Document objects describe entities in the CMIS repository. A document object with content
contains a content stream that is the actual file contents, and a mimetype for the content stream.
So, to create a document Object, first you need a content stream
- :::java
- final String textFileName = "test.txt";
- System.out.println("creating a simple text file, " + textFileName);
- String mimetype = "text/plain; charset=UTF-8";
- String content = "This is some test content.";
- String filename = textFileName;
+ :::java
+ final String textFileName = "test.txt";
+ System.out.println("creating a simple text file, " + textFileName);
+
+ String mimetype = "text/plain; charset=UTF-8";
+ String content = "This is some test content.";
+ String filename = textFileName;
- byte[] buf = null;
- try {
- buf = content.getBytes("UTF-8");
- } catch (UnsupportedEncodingException e) {
- e.printStackTrace();
- }
- ByteArrayInputStream input = new ByteArrayInputStream(buf);
- ContentStream contentStream = session.getObjectFactory().createContentStream(filename,
- buf.length, mimetype, input);
+ byte[] buf = content.getBytes("UTF-8");
+ ByteArrayInputStream input = new ByteArrayInputStream(buf);
+
+ ContentStream contentStream = session.getObjectFactory().createContentStream(filename, buf.length, mimetype, input);
To add a document with some content to the repository, you use the `createDocument()` method on the parent folder, and provide the content stream
and a map of properties which define the object to be created.
- :::java
- Map<String, Object> properties = new HashMap<String, Object>();
- properties.put(PropertyIds.OBJECT_TYPE_ID, "cmis:document");
- properties.put(PropertyIds.NAME, filename);
- ObjectId id = newFolder.createDocument(properties, contentStream, VersioningState.MAJOR);
+ :::java
+ Map<String, Object> properties = new HashMap<String, Object>();
+ properties.put(PropertyIds.OBJECT_TYPE_ID, "cmis:document");
+ properties.put(PropertyIds.NAME, filename);
+
+ Document doc = newFolder.createDocument(properties, contentStream, VersioningState.MAJOR);
+
+ System.out.println("Document ID: " + doc.getId());
Note the following points :-
-* The `createDocument()` method returns the Object ID of the newly created document object.
+* The `createDocument()` method returns the newly created document object.
* Each version of a document object has its own object ID.
* You can create a document without an associated content stream, by passing null as the contentStream Parameter.
@@ -358,15 +355,15 @@ The following code snippet retrieves the
:::java
// Get the contents of the file
- doc = (Document) session.getObject(id);
- try {
- content = getContentAsString(doc.getContentStream());
- } catch (IOException e) {
- e.printStackTrace();
+ Document doc = (Document) session.getObject(id);
+ ContentStream contentStream = doc.getContentStream(); // returns null if the document has no content
+ if (contentStream != null) {
+ String content = getContentAsString(contentStream);
+ System.out.println("Contents of " + filename + " are: " + content);
+ } else {
+ System.out.println("No content.");
}
- System.out.println("Contents of " + filename + " are: " + content);
-
...
/**
@@ -403,19 +400,19 @@ The following code snippet retrieves the
:::java
String path = newFolder.getPath() + "/" + textFileName;
System.out.println("Getting object by path " + path);
- doc = (Document) session.getObjectByPath(path);
- try {
- content = getContentAsString(doc.getContentStream());
- } catch (IOException e) {
- e.printStackTrace();
+
+ Document doc = (Document) session.getObjectByPath(path);
+ ContentStream contentStream = doc.getContentStream();
+ if (contentStream != null) {
+ String content = getContentAsString(contentStream);
}
-
+
Note the following points :-
* All paths start with the root folder `/`.
-* The [`Document`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/Document.html)
+* The [`Document`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/Document.html)
class does not have a `getPath()` method, since multifiling means a document can have more than one parent folder. It does implement the
-`getPaths()` method from the [`FileableCmisObject`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/FileableCmisObject.html) interface.
+`getPaths()` method from the [`FileableCmisObject`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/FileableCmisObject.html) interface.
This returns a list of the current paths to the document object.
#### Updating a document.
@@ -428,12 +425,15 @@ The following code snippet updates the n
:::java
Document doc2 = (Document) session.getObject(id2);
System.out.println("renaming " + doc2.getName() + " to test3.txt");
- properties = new HashMap<String, Object>();
+
+ Map<String, String> properties = new HashMap<String, Object>();
properties.put(PropertyIds.NAME, "test3.txt");
- id2 = doc2.updateProperties(properties);
+
+ doc2.updateProperties(properties, true);
+
System.out.println("renamed to " + doc2.getName());
-You can update the contents of a document by setting a new [ContentStream](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/commons/data/ContentStream.html)
+You can update the contents of a document by setting a new [ContentStream](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/commons/data/ContentStream.html)
using the `setContentStream()` 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 `test3.txt` document:-
@@ -443,28 +443,25 @@ You must set the overwrite flag if the d
System.out.println("update without checkout not supported in this repository");
} else {
System.out.println("updating content stream");
- content = "This is some updated test content for our renamed second document.";
- buf = null;
- try {
- buf = content.getBytes("UTF-8");
- } catch (UnsupportedEncodingException e) {
- e.printStackTrace();
- }
+
+ String mimetype = "text/plain; charset=UTF-8";
+ String content = "This is some updated test content for our renamed second document.";
+ byte[] buf = content.getBytes("UTF-8");
input = new ByteArrayInputStream(buf);
- contentStream = session.getObjectFactory().createContentStream("test3.txt", buf.length,
- mimetype, input);
- properties = new HashMap<String, Object>();
- properties.put(PropertyIds.OBJECT_TYPE_ID, "cmis:document");
- properties.put(PropertyIds.NAME, "test3.txt");
+
+ ContentStream contentStream = session.getObjectFactory().createContentStream("test3.txt", buf.length, mimetype, input);
+
doc2.setContentStream(contentStream, true);
// did it work?
- try {
- content = getContentAsString(doc2.getContentStream());
- } catch (IOException e) {
- e.printStackTrace();
+ contentStream = doc2.getContentStream();
+
+ if (contentStream != null) {
+ content = getContentAsString(contentStream);
+ System.out.println("Contents of " + doc2.getName() + " are: " + content);
+ } else {
+ System.out.println("Something went wrong.");
}
- System.out.println("Contents of " + doc2.getName() + " are: " + content);
}
Note that this code snippet will not work for repositories that require a checkout to set a content stream.
@@ -476,18 +473,21 @@ You can delete any CMIS object using the
contents of the test folder before and after a delete of one of the two documents
in the folder.
- :::java
- children = newFolder.getChildren();
- System.out.println("Now finding the following objects in our folder:-");
- for (CmisObject o : children) {
- System.out.println(o.getName());
- }
- System.out.println("Deleting document " + doc2.getName());
- doc2.delete(true);
- System.out.println("Now finding the following objects in our folder:-");
- for (CmisObject o : children) {
- System.out.println(o.getName());
- }
+ :::java
+ ItemIterable<CmisObject> children = newFolder.getChildren();
+ System.out.println("Now finding the following objects in our folder:-");
+
+ for (CmisObject o : children) {
+ System.out.println(o.getName());
+ }
+
+ System.out.println("Deleting document " + doc2.getName());
+ doc2.delete(true);
+
+ System.out.println("Now finding the following objects in our folder:-");
+ for (CmisObject o : children) {
+ System.out.println(o.getName());
+ }
Note that the `allVersions` flag is set to `true`. If you set it to false then the delete will
be of this version only.
@@ -500,14 +500,17 @@ all versions of any documents in the tre
:::java
System.out.println("Creating 'ADGFolder1' in the root folder");
- newFolderProps = new HashMap<String, String>();
+ Map<String, String> newFolderProps = new HashMap<String, String>();
newFolderProps.put(PropertyIds.OBJECT_TYPE_ID, "cmis:folder");
newFolderProps.put(PropertyIds.NAME, "ADGFolder1");
Folder folder1 = root.createFolder(newFolderProps);
+
newFolderProps.put(PropertyIds.NAME, "ADGFolder11");
Folder folder11 = folder1.createFolder(newFolderProps);
+
newFolderProps.put(PropertyIds.NAME, "ADGFolder12");
Folder folder12 = folder1.createFolder(newFolderProps);
+
System.out.println("delete the 'ADGFolder1' tree");
folder1.deleteTree(true, UnfileObject.DELETE, true);
@@ -529,12 +532,12 @@ up a tree in the repository that looks l
The following snippet from the getting started sample will print out the children of a folder :-
- :::java
- children = folder1.getChildren();
- System.out.println("Children of " + folder1.getName() + ":-");
- for (CmisObject o : children) {
- System.out.println(o.getName());
- }
+ :::java
+ ItemIterable<CmisObject> children = folder1.getChildren();
+ System.out.println("Children of " + folder1.getName() + ":-");
+ for (CmisObject o : children) {
+ System.out.println(o.getName());
+ }
Note that the children of a Folder object can be of any type supported by the repository.
Running the sample produces the following output :-
@@ -569,7 +572,7 @@ This code snippet uses a recursive metho
Note the following points:-
-1. The children of a [`Tree`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/Tree.html) are themselves of type `Tree`.
+1. The children of a [`Tree`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/Tree.html) are themselves of type `Tree`.
1. The single argument of `getDescendants` 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.
@@ -651,22 +654,26 @@ So, we can retrieve information in the t
System.out.println("Getting type definition for doc type");
ObjectType objectType = session.getTypeDefinition(doc.getType().getId());
System.out.println("isBaseType() returns " + (objectType.isBaseType() ? "true" : "false"));
+
ObjectType baseType = objectType.getBaseType();
if (baseType == null) {
System.out.println("getBaseType() returns null");
} else {
System.out.println("getBaseType() returns " + baseType.getDisplayName());
}
+
ObjectType parentType = objectType.getParentType();
if (parentType == null) {
System.out.println("getParentType() returns null");
} else {
System.out.println("getParentType() returns " + parentType.getDisplayName());
}
+
System.out.println("Listing child types of " + objectType.getDisplayName());
for (ObjectType o : objectType.getChildren()) {
System.out.println("\t" + o.getDisplayName());
}
+
System.out.println("Getting immediate descendant types of " + objectType.getDisplayName());
for (Tree<ObjectType> o : objectType.getDescendants(1)) {
System.out.println("\t" + o.getItem().getDisplayName());
@@ -699,17 +706,15 @@ you are running this code against, there
#### Displaying the properties of an Object
-All objects of the CMIS base types implement the interface [`CmisObjectProperties`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/CmisObjectProperties.html) which provides
+All objects of the CMIS base types implement the interface [`CmisObjectProperties`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/CmisObjectProperties.html) which provides
accessors to CMIS object properties. The following code snippet uses the `getProperties()` method
to print out all the available properties on a newly created Document object, doc.
- :::java
- List<Property<?>> props = doc.getProperties();
- for (Property<?> p : props) {
- System.out.println(p.getDefinition().getDisplayName() + "=" +
- p.getValuesAsString()
- );
- }
+ :::java
+ List<Property<?>> props = doc.getProperties();
+ for (Property<?> p : props) {
+ System.out.println(p.getDefinition().getDisplayName() + "=" + p.getValuesAsString());
+ }
The output should look something like this :-
@@ -740,26 +745,24 @@ The output should look something like th
####Getting a property explicitly
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 [`DocumentProperties`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/DocumentProperties.html) interface,
+For example, the document type has a set of properties described by the [`DocumentProperties`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/DocumentProperties.html) interface,
and you can use the methods on this interface to retrieve
the value a property:-
- :::java
- System.out.println("VersionLabel property on " + doc.getName() + " is "
- + doc.getVersionLabel());
- System.out.println("Is this the latest version of " + doc.getName() + " ?: "
- + (doc.isLatestVersion() ? "yes" : "no"));
+ :::java
+ System.out.println("VersionLabel property on " + doc.getName() + " is "
+ + doc.getVersionLabel());
+ System.out.println("Is this the latest version of " + doc.getName() + " ?: "
+ + (doc.isLatestVersion() ? "yes" : "no"));
Note that properties can be of simple types, `Boolean`, String, long, or more complex types,
such as `GregorianCalendar`. The following code snippet prints out the `CreationDate` property:-
- :::java
- GregorianCalendar calendar = doc.getCreationDate();
- String DATE_FORMAT = "yyyyMMdd";
- SimpleDateFormat sdf = new SimpleDateFormat(DATE_FORMAT);
- System.out.println("Creation date of " + doc.getName() + " is "
- + sdf.format(calendar.getTime())
- );
+ :::java
+ GregorianCalendar calendar = doc.getCreationDate();
+ String DATE_FORMAT = "yyyyMMdd";
+ SimpleDateFormat sdf = new SimpleDateFormat(DATE_FORMAT);
+ System.out.println("Creation date of " + doc.getName() + " is " + sdf.format(calendar.getTime()));
#### Getting a property value by Id
@@ -771,10 +774,9 @@ property's value using the `queryName`:-
:::java
List<Property<?>> props = doc.getProperties();
Property<?> someProperty = props.get(0);
- System.out
- .println(someProperty.getDisplayName() + " property on " + doc.getName()
- + " (by getPropertValue()) is "
- + doc.getPropertyValue(someProperty.getId()));
+ System.out.println(someProperty.getDisplayName() + " property on " + doc.getName()
+ + " (by getPropertValue()) is "
+ + doc.getPropertyValue(someProperty.getId()));
#### Getting a property value by query name
@@ -850,22 +852,20 @@ in this particular query. This code snip
If something goes wrong in an OpenCMIS method, an exception will be thrown.
All OpenCMIS exceptions extend
-[`CmisBaseException`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html)
+[`CmisBaseException`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html)
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
-[`CmisInvalidArgumentException`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/CmisInvalidArgumentException.html)
+[`CmisInvalidArgumentException`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/CmisInvalidArgumentException.html)
by supplying a null content stream.
- :::java
- try {
- doc2.setContentStream(null, false);
- } catch (CmisInvalidArgumentException e1) {
- System.err.println("caught an " + e1.getClass().getName() + " exception with message "
- + e1.getMessage());
- }
-
+ :::java
+ try {
+ doc2.setContentStream(null, false);
+ } catch (CmisInvalidArgumentException e) {
+ System.err.println("caught an " + e.getClass().getName() + " exception with message " + e.getMessage());
+ }
-If you are using the ATOMPUB binding, [`CmisBaseException`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html)
+If you are using the ATOMPUB binding, [`CmisBaseException`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html)
provides a `getErrorContent()` 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.
In the following code snippet, a `CmisObjectNotFoundException` exception is forced by
@@ -886,8 +886,8 @@ and the client stack trace.
try {
folderTest.createDocument(newFileProps, null, VersioningState.MAJOR);
- } catch (CmisObjectNotFoundException e1) {
- System.err.println("server error page :\n" + e1.getErrorContent());
+ } catch (CmisObjectNotFoundException e) {
+ System.err.println("server error page :\n" + e.getErrorContent());
System.err.println("\nClient stack trace :\n");
e1.printStackTrace();
}
@@ -911,7 +911,7 @@ The output from this snippet looks like
###Operation Context
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 [`OperationContext`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/OperationContext.html).
+and provide additional methods that take an [`OperationContext`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/OperationContext.html).
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.
@@ -922,15 +922,15 @@ or `getObjectByPath()` will not return s
:::java
OperationContext operationContext = session.createOperationContext();
- oc.setCacheEnabled(false);
- CmisObject object = session.getObject(id, oc);
+ operationContext.setCacheEnabled(false);
+ CmisObject object = session.getObject(id, operationContext);
####Rendition Filter
For example the following code snippet looks like it retrieves a list of renditions for a document object.
- :::java
- CmisObject oo = session.getObject(o.getId());
- List<Rendition> rl = oo.getRenditions();
+ :::java
+ CmisObject oo = session.getObject(o.getId());
+ List<Rendition> rl = oo.getRenditions();
The client will now have access to the default set of information, but this code will
return an empty list, even when there are renditions associated with the document object.
@@ -938,11 +938,11 @@ This is because renditions are not inclu
You can use an `OperationContext` with a rendition filter to extend the information retrieved:-
- :::java
- OperationContext operationContext = session.createOperationContext();
- context.setRenditionFilterString("cmis:thumbnail");
- CmisObject oo = session.getObject(o.getId(), context);
- List<Rendition> rl = oo.getRenditions();
+ :::java
+ OperationContext operationContext = session.createOperationContext();
+ operationContext.setRenditionFilterString("cmis:thumbnail");
+ CmisObject oo = session.getObject(o.getId(), operationContext);
+ List<Rendition> rl = oo.getRenditions();
This code will retrieve any renditions of type `cmis:thumbnail` for this document object.
@@ -956,16 +956,15 @@ The `OperationContext` specifies the max
The following code snippet retrieves a page of three objects from the result set, starting at the fifth item.
- :::java
- OperationContext operationContext = new OperationContextImpl();
- operationContext.setMaxItemsPerPage(3);
- ItemIterable<CmisObject> children1 = folderPaging.getChildren(operationContext);
- int count = 0;
- for (CmisObject child : children1.skipTo(5).getPage()) {
- System.out.println("object " + count + " in page of " + children1.getPageNumItems()
- + " is " + child.getName());
- count++;
- }
+ :::java
+ OperationContext operationContext = session.createOperationContext();
+ operationContext.setMaxItemsPerPage(3);
+ ItemIterable<CmisObject> children1 = folderPaging.getChildren(operationContext);
+ int count = 0;
+ for (CmisObject child : children1.skipTo(5).getPage()) {
+ System.out.println("object " + count + " in page of " + children1.getPageNumItems() + " is " + child.getName());
+ count++;
+ }
Note that `skipTo()` method returns a an iterable over the complete collection. The `getPage()` method is then be used to create an iterable over the page.
@@ -973,7 +972,7 @@ The following code snippet retrieves all
:::java
System.out.println("Getting complete result set in pages of 3");
- operationContext = new OperationContextImpl();
+ OperationContext operationContext = session.createOperationContext();
operationContext.setMaxItemsPerPage(3);
children1 = folderPaging.getChildren(operationContext);
int pageNumber = 0;
@@ -1042,21 +1041,21 @@ without having to perform the action its
influenced by ACLs, constraints on the object's base type, and policies or other mechanisms not specified by CMIS. The following code snippet
gets the current allowable actions for the test.txt document object:-
- :::java
- System.out.println("Getting the current allowable actions for the " + doc.getName() + " document object...");
- for (Action a: doc.getAllowableActions().getAllowableActions()) {
- System.out.println("\t" + a.value());
- }
+ :::java
+ System.out.println("Getting the current allowable actions for the " + doc.getName() + " document object...");
+ for (Action a: doc.getAllowableActions().getAllowableActions()) {
+ System.out.println("\t" + a.value());
+ }
In practice, you would check a single allowable action before executing that action. So, the following code snippet shows how to check if
your application is currently allowed to check out the document `test.txt`
- :::java
- if (doc.getAllowableActions().getAllowableActions().contains(Action.CAN_CHECK_OUT)) {
- System.out.println("can check out " + doc.getName());
- } else {
- System.out.println("can not check out " + doc.getName());
- }
+ :::java
+ if (doc.getAllowableActions().getAllowableActions().contains(Action.CAN_CHECK_OUT)) {
+ System.out.println("can check out " + doc.getName());
+ } else {
+ System.out.println("can not check out " + doc.getName());
+ }
###Multi-filing and Unfiling
@@ -1075,23 +1074,23 @@ and the code checks for this.
} else {
// Add a new folder to the root folder
System.out.println("Creating 'ADGNewFolder 2' in the root folder");
- newFolderProps = new HashMap<String, String>();
+ Map<String, Object> newFolderProps = new HashMap<String, Object>();
newFolderProps.put(PropertyIds.OBJECT_TYPE_ID, "cmis:folder");
newFolderProps.put(PropertyIds.NAME, "ADGNewFolder 2");
- newFolder2 = root.createFolder(newFolderProps, null, null, null,
- session.getDefaultContext());
+ newFolder2 = root.createFolder(newFolderProps);
+
System.out.println("Adding " + textFileName + "to 'ADGNewFolder 2' in the root folder");
doc.addToFolder(newFolder2, true);
// Did it work?
- children = newFolder.getChildren();
+ ItemIterable<CmisObject>children = newFolder.getChildren();
System.out.println("Now finding the following objects in the 'ADGNewFolder' folder:-");
for (CmisObject o : children) {
System.out.println(o.getName());
}
+
children = newFolder2.getChildren();
- System.out
- .println("Now finding the following objects in the 'ADGNewFolder 2' folder:-");
+ System.out.println("Now finding the following objects in the 'ADGNewFolder 2' folder:-");
for (CmisObject o : children) {
System.out.println(o.getName());
}
@@ -1109,14 +1108,15 @@ and the code checks for this.
// remove our document from both folders
System.out.println("removing :" + doc.getName() + "from 'ADGNewFolder':-");
doc.removeFromFolder(newFolder);
+
System.out.println("removing :" + doc.getName() + "from 'ADGNewFolder 2':-");
doc.removeFromFolder(newFolder2);
+
// Did it work?
Document docTest = (Document) session.getObject(id);
if (docTest != null) {
System.out.println(docTest.getName() + " still exists");
}
-
}
<a name="Versioning"></a>
@@ -1137,12 +1137,12 @@ Version Series need not have a Latest Ma
The following code snippet checks if the test.txt document object is versionable.
- :::java
- if (((DocumentType)(doc.getType())).isVersionable()) {
- System.out.println(doc.getName() + " is versionable");
- } else {
- System.out.println(doc.getName() + " is NOT versionable");
- }
+ :::java
+ if (((DocumentType)(doc.getType())).isVersionable()) {
+ System.out.println(doc.getName() + " is versionable");
+ } else {
+ System.out.println(doc.getName() + " is NOT versionable");
+ }
You create new version of a document by checking-in a Private Working copy (PWC) of the object.
A PWC is created by checking-out a document.
@@ -1150,54 +1150,59 @@ Repositories may allow any version of a
The following code snippet checks out the latest version of the test.txt document, updates the content stream, and checks in the new version of the
document as a minor version.
- :::java
- if (versionable) {
- Document pwc = (Document) session.getObject(doc.checkOut());
- try {
- content = getContentAsString(pwc.getContentStream());
- } catch (IOException e) {
- e.printStackTrace();
- }
- String updatedContents = content + "\nLine added in new version";
-
- try {
- buf = updatedContents.getBytes("UTF-8");
- } catch (UnsupportedEncodingException e) {
- e.printStackTrace();
- }
- contentStream = session.getObjectFactory().createContentStream(
- doc.getContentStream().getFileName(), buf.length,
- doc.getContentStream().getMimeType(), new ByteArrayInputStream(buf));
+ if (versionable) {
+ Document pwc = (Document) session.getObject(doc.checkOut());
+
+ // default values if the document has no content
+ String filename = "version.txt";
+ String mimetype = "text/plain; charset=UTF-8";
+ String content = "";
+
+ // get the orginal content
+ ContentStream contentStream = doc.getContentStream();
+ if (contentStream != null) {
+ filename = contentStream.getFileName();
+ mimetype = contentStream.getMimeType();
+ content = getContentAsString(contentStream);
+ }
+
+ String updatedContents = content + "\nLine added in new version";
+
+ byte[] buf = updatedContents.getBytes("UTF-8");
+ ByteArrayInputStream input = new ByteArrayInputStream(buf);
+
+ contentStream = session.getObjectFactory().createContentStream(
+ filename, buf.length, mimetype, input);
- // Check in the pwc
- try {
- pwc.checkIn(false, null, contentStream, "minor version");
- } catch (Exception e) {
- e.printStackTrace();
- System.out.println("checkin failed, trying to cancel the checkout");
- pwc.cancelCheckOut();
- }
+ // Check in the pwc
+ try {
+ pwc.checkIn(false, null, contentStream, "minor version");
+ } catch (CmisBaseException e) {
+ e.printStackTrace();
+ System.out.println("checkin failed, trying to cancel the checkout");
+ pwc.cancelCheckOut();
+ }
- System.out.println("Document version history");
- {
- List<Document> versions = doc.getAllVersions();
- for (Document version : versions) {
- System.out.println("\tname: " + version.getName());
- System.out.println("\tversion label: " + version.getVersionLabel());
- System.out.println("\tversion series id: " + version.getVersionSeriesId());
- System.out.println("\tchecked out by: "
- + version.getVersionSeriesCheckedOutBy());
- System.out.println("\tchecked out id: "
- + version.getVersionSeriesCheckedOutId());
- System.out.println("\tmajor version: " + version.isMajorVersion());
- System.out.println("\tlatest version: " + version.isLatestVersion());
- System.out.println("\tlatest major version: " + version.isLatestMajorVersion());
- System.out.println("\tcheckin comment: " + version.getCheckinComment());
- System.out.println("\tcontent length: " + version.getContentStreamLength()
- + "\n");
- }
+ System.out.println("Document version history");
+ {
+ List<Document> versions = doc.getAllVersions();
+ for (Document version : versions) {
+ System.out.println("\tname: " + version.getName());
+ System.out.println("\tversion label: " + version.getVersionLabel());
+ System.out.println("\tversion series id: " + version.getVersionSeriesId());
+ System.out.println("\tchecked out by: "
+ + version.getVersionSeriesCheckedOutBy());
+ System.out.println("\tchecked out id: "
+ + version.getVersionSeriesCheckedOutId());
+ System.out.println("\tmajor version: " + version.isMajorVersion());
+ System.out.println("\tlatest version: " + version.isLatestVersion());
+ System.out.println("\tlatest major version: " + version.isLatestMajorVersion());
+ System.out.println("\tcheckin comment: " + version.getCheckinComment());
+ System.out.println("\tcontent length: " + version.getContentStreamLength()
+ + "\n");
}
}
+ }
The code snippet uses the `getAllVersions()` method to retrieve all the versions in the version series.
The output from this code snippet will look something like this:-
@@ -1247,8 +1252,7 @@ to retrieve all renditions of a particul
.equals(CapabilityRenditions.NONE)) {
System.out.println("Repository does not support renditions");
} else {
- System.out
- .println("Finding first object in repository with thumbnail renditions - start");
+ System.out.println("Finding first object in repository with thumbnail renditions - start");
Folder node = root;
Stack<Folder> stack = new Stack<Folder>();
while (node != null) {
@@ -1275,7 +1279,6 @@ to retrieve all renditions of a particul
break; // Just show the first object with
// renditions. Remove this
// Break to show them all
-
}
}
}
@@ -1285,9 +1288,9 @@ to retrieve all renditions of a particul
node = (Folder) stack.pop();
}
}
- System.out
- .println("Finding first object in repository with thumbnail renditions - end");
+ System.out.println("Finding first object in repository with thumbnail renditions - end");
}
+
###Advanced use of types
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
@@ -1365,10 +1368,10 @@ relationship type.
} catch (CmisObjectNotFoundException e) {
cmiscustomRelationshipType = null;
}
+
if (cmiscustomRelationshipType == null) {
System.out.println("Repository does not support R:cmiscustom:assoc objects");
} else {
-
System.out.println("Creating folders for relationships example");
newFolderProps = new HashMap<String, String>();
@@ -1379,12 +1382,11 @@ relationship type.
newFileProps = new HashMap<String, String>();
newFileProps.put(PropertyIds.OBJECT_TYPE_ID, "D:cmiscustom:document");
newFileProps.put(PropertyIds.NAME, "ADGFileSource");
- Document sourceDoc = folderAssociations.createDocument(newFileProps, null,
- VersioningState.MAJOR);
+ Document sourceDoc = folderAssociations.createDocument(newFileProps, null, VersioningState.MAJOR);
+
newFileProps.put(PropertyIds.OBJECT_TYPE_ID, "cmis:document");
newFileProps.put(PropertyIds.NAME, "ADGFileTarget");
- Document targetDoc = folderAssociations.createDocument(newFileProps, null,
- VersioningState.MAJOR);
+ Document targetDoc = folderAssociations.createDocument(newFileProps, null, VersioningState.MAJOR);
Map<String, String> relProps = new HashMap<String, String>();
relProps.put("cmis:sourceId", sourceDoc.getId());
@@ -1392,7 +1394,6 @@ relationship type.
relProps.put("cmis:objectTypeId", "R:cmiscustom:assoc");
ObjectId relId = session.createRelationship(relProps, null, null, null);
System.out.println("created relationship");
-
}
}
@@ -1436,7 +1437,7 @@ There are three basic permissions predef
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
-[`getRepositoryInfo`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/Session.html#getRepositoryInfo()).
+[`getRepositoryInfo`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/client/api/Session.html#getRepositoryInfo()).
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:-
@@ -1485,6 +1486,7 @@ prints out the ACEs now present in the d
HashMap<String, String> newFileProps = new HashMap<String, String>();
ContentStream contentStream = new ContentStreamImpl("permissions.txt", null,
"plain/text", new ByteArrayInputStream("some content".getBytes()));
+
newFileProps.put(PropertyIds.OBJECT_TYPE_ID, "cmis:document");
newFileProps.put(PropertyIds.NAME, "ADGFilePermissions");
Document testDoc = folderAssociations.createDocument(newFileProps, contentStream,
@@ -1537,10 +1539,10 @@ OpenCMIS provides a number of features w
object.
##Troubleshooting
-* When handling CMIS exceptions in a CMIS client which connects with the AtomPub binding, remember that [`CmisBaseException`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html)
+* When handling CMIS exceptions in a CMIS client which connects with the AtomPub binding, remember that [`CmisBaseException`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html)
provides a `getErrorContent()` 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.
-* When handling CMIS exceptions in a CMIS client which connects with the Web Services binding, [`CmisBaseException`](http://chemistry.apache.org/java/0.4.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html)
+* When handling CMIS exceptions in a CMIS client which connects with the Web Services binding, [`CmisBaseException`](http://chemistry.apache.org/java/0.8.0/maven/apidocs/org/apache/chemistry/opencmis/commons/exceptions/package-tree.html)
provides a `getCode()` method which returns the error code returned from the server, if there is one.
* If a `java.lang.NullPointerException` 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
`OperationContext` when getting the object, or you have not set the `OperationContext` properly.
\ No newline at end of file