chemistry-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r1085470 - in /chemistry/site/trunk/content: ./ java/ java/developing/ java/developing/client/ java/examples/
Date Fri, 25 Mar 2011 16:57:27 GMT
Author: fmui
Date: Fri Mar 25 16:57:26 2011
New Revision: 1085470

a bit more OpenCMIS client documentation


Modified: chemistry/site/trunk/content/index.mdtext
--- chemistry/site/trunk/content/index.mdtext (original)
+++ chemistry/site/trunk/content/index.mdtext Fri Mar 25 16:57:26 2011
@@ -7,7 +7,8 @@ Title: Index
 Apache Chemistry provides open source implementations of the
  [Content Management Interoperability Services (CMIS)](
- specification. See the [What is CMIS?](project/cmis.html) page for more information about
the standard.
+ specification.  
+See the [What is CMIS?](project/cmis.html) page for more information about the standard.
 The project currently consists of the following sub-projects:
@@ -17,9 +18,9 @@ The project currently consists of the fo
 * [DotCMIS](dotnet/dotcmis.html) - CMIS client library for .NET
 Chemistry mailing list for questions and contributions:
-Important time-saving note for chemists: the Apache Chemistry project has
+*Important time-saving note for chemists:* the Apache Chemistry project has
 nothing to do with chemistry or chemicals! The name comes from the
 inclusion of the C.M.I.S. letters, "CheMIStry".

Modified: chemistry/site/trunk/content/java/developing/client/dev-client-overview.mdtext
--- chemistry/site/trunk/content/java/developing/client/dev-client-overview.mdtext (original)
+++ chemistry/site/trunk/content/java/developing/client/dev-client-overview.mdtext Fri Mar
25 16:57:26 2011
@@ -1,10 +1,68 @@
 Title: CMIS Client Overview
-# CMIS Client Overview
+# OpenCMIS Client Development
+The OpenCMIS client API provides an easy way to connect to CMIS repositories. This is a short
step-by-step guide.
+## Prerequisite
+1. Read the second chapter of the [CMIS specification](
You can skip the other chapters but you need to understand the CMIS domain model to in order
to use OpenCMIS.
+1. Set up your repository. Some repositories provide CMIS out-of-the-box. Other repositories
require an update, a module, a service pack, or something like that.
+1. Select your binding. The CMIS specification defines two bindings, AtomPub and Web Services.
Check which binding your repository supports. If the repository supports both, go for the
AtomPub binding. In most cases it is the better choice. But don't worry; you can switch the
binding at any time. The OpenCMIS API is not binding specific.
+1. Check which authentication method the repository provides. Refer to the authentication
section for more information. 
+1. Make sure your repository speaks HTTPS. You probably don't want to expose your password
and your documents to everyone on the network.
+1. Download the [OpenCMIS client library](../download.html) and the [CMIS Workbench](../download.html)
+1. Choose an API. OpenCMIS provides two CMIS client APIs that are called [Client API](dev-client-api.html)
and [Client Bindings API](dev-client-bindings.html). The Client API is a high-level, object
orientated API and suitable for most use cases. It sits on top of the Client Bindings API.
The Client Bindings API reflects the CMIS domain model. It allows fine-grained control, which
makes the interfaces a bit clunky. This guide explains the Client API and [this page](dev-compare-client-api-binding.html)
compares both.
+## The Theory
+CMIS is stateless. That has a few implications.
+It scales well since each call can go to a different cluster node. But it also implies that
each call has to contain authentication information. It also makes the client responsible
for the information it pulls from the repository. And this has a direct effect on the application
performance. Keep in mind that CMIS sends and receives XML over HTTP. Avoiding such a call
can save valuable time.
+OpenCMIS introduces a session concept on top of CMIS and provides a set of caches that help
reducing the number of calls and the amount of transmitted data. 
+The central object of the client API is the Session object. It manages the authentication,
all caches and provides the entry point to all CMIS operations. A Session object is bound
to a user and therefore there is a set of separate caches per user. The repository might send
different data for different users, for example to obey permissions or provide localized display
names and property values. Therefore it is not possible to manage a shared cache. (The Client
Bindings API is more flexible in this respect but also requires more effort and care.)
+In order to be effective, this Session object has to be reused as much as possible! Don't
throw it away. Keep it and reuse it! OpenCMIS is thread-safe. The Session object can and should
be reused across thread boundaries.
+## First Steps
+The OpenCMIS client package contains all jars you need to connect to a repository. Make sure
they are all in your classpath.
+Before you start implementing have a look at the OpenCMIS JavaDoc. Start with the Session
interface, the Document interface, and the Folder interface. Together with your CMIS domain
model knowledge (you remember the second chapter of the CMIS specification) you should now
have a picture of what is available. 
+To connect to a repository you have to create a Session object. See [this page](../examples/example-create-session.html)
for code examples. There are a few required entries in the session parameters map. OpenCMIS
has to know which binding you want to use and where to find the CMIS endpoint. Most repositories
also need a username and a password to identify the user. (See the authentication section
for more details.)
+The repository id parameter tells OpenCMIS which repository at this CMIS endpoint it should
talk to. How do you get this repository id is repository specific. The SessionFactory can
also fetch a list of all available repositories. 
+There are also a number of optional [session parameters](dev-session-parameters.html) that
control the cache behavior, HTTP settings, etc. Leave them alone as long as you don't want
or have to optimize your setup.
+The Session object gives you access to all CMIS features.  There are a few common and repeating
patterns. Have a look at the [examples sections](../examples/index.html).
+When you feel comfortable with the API, familiarize yourself with the [OpenCMIS caches](dev-client-cache.html)
and the [OperationContext](dev-operation-context.html). They can improve the performance considerably.
+## Authentication
+The CMIS specification recommends HTTP basic authentication for AtomPub and WS-Security UsernameToken
for Web Services. Most repositories support that. If can't find any information in the repository
documentation, assume that those are enabled.
+OpenCMIS also supports [NTLM](dev-session-parameters.html) but you should avoid it if you
can. It generates some side effects in the JVM and has streaming issues. 
+If the repository need requires a different authentication mechanism, you have to implement
your own [authentication provider](dev-client-bindings.html).
+## CMIS Workbench
+The CMIS Workbench is desktop client build on top of OpenCMIS. It lets you see the repository
through the eyes of CMIS and OpenCMIS. That can be handy during development.
+You should also play with console that is built into the CMIS Workbench. It runs code snippets
and lets you experiment with the OpenCMIS client API without setting up a full-blown Java
-OpenCMIS provides two CMIS client APIs that are called [Client API](dev-client-api.html)
and [Client Bindings API](dev-client-bindings.html).
-The [Client API](dev-client-api.html) is a high-level, object orientated API and suitable
for most use cases.
-It sits on top of the Client Bindings API.
-The [Client Bindings API](dev-client-bindings.html) reflects the CMIS domain model.
-It allows fine-grained control which makes the interfaces a bit clunky.

Modified: chemistry/site/trunk/content/java/developing/dev-session-parameters.mdtext
--- chemistry/site/trunk/content/java/developing/dev-session-parameters.mdtext (original)
+++ chemistry/site/trunk/content/java/developing/dev-session-parameters.mdtext Fri Mar 25
16:57:26 2011
@@ -8,8 +8,8 @@ Key|Constant|Description|Values|Required
 org.apache.chemistry.opencmis.binding.spi.type|BINDING_TYPE|Binding to use for the session
|"atompub", "webservices", "local", "custom"|yes
 org.apache.chemistry.opencmis.binding.spi.classname|BINDING_SPI_CLASS|Binding implementation
class|class name|Custom binding: yes<br/>other binding: no|Depends on BINDING_TYPE|REPOSITORY_ID|Repository id|repository
id|createSession(): yes<br/>getRepositories(): no
-org.apache.chemistry.opencmis.user|USER|User name<br/>(used by standard authentication
-org.apache.chemistry.opencmis.password|PASSWORD|Password<br/>(used by standard authentication
+org.apache.chemistry.opencmis.user|USER|User name<br/>(used by the standard authentication
+org.apache.chemistry.opencmis.password|PASSWORD|Password<br/>(used by the standard
authentication provider)|string
 org.apache.chemistry.opencmis.locale.iso639|LOCALE_ISO639_LANGUAGE|Language code sent to
server|ISO 639 code|no
 org.apache.chemistry.opencmis.locale.iso3166|LOCALE_ISO3166_COUNTRY|Country code sent to
server if language code is set|ISO 3166 code|no
 org.apache.chemistry.opencmis.binding.atompub.url|ATOMPUB_URL|AtomPub service document URL|URL|AtomPub
binding: yes<br/>other bindings: no

Modified: chemistry/site/trunk/content/java/developing/index.mdtext
--- chemistry/site/trunk/content/java/developing/index.mdtext (original)
+++ chemistry/site/trunk/content/java/developing/index.mdtext Fri Mar 25 16:57:26 2011
@@ -2,7 +2,7 @@ Title: Developing with OpenCMIS
 # Developing with OpenCMIS
-General guidelines you should know when developing with OpenCMIS
+General guidelines you should know when developing with OpenCMIS.
 * Developing using the client APIs
 	* [Overview](client/dev-client-overview.html)

Modified: chemistry/site/trunk/content/java/examples/example-create-session.mdtext
--- chemistry/site/trunk/content/java/examples/example-create-session.mdtext (original)
+++ chemistry/site/trunk/content/java/examples/example-create-session.mdtext Fri Mar 25 16:57:26
@@ -75,3 +75,15 @@ The local binding is specific to OpenCMI
     // create session
     Session session = factory.createSession(parameter);
+## Connect to the first repository
+Some CMIS endpoints only provide one repository. In this case it is not necessary to provide
its repository id.  
+The following code snippet gets the list of all available repositories and connects to the
first one.
+    ::java
+    List<Repository> repositories = factory.getRepositories(parameter);
+    Session session = repositories.get(0).createSession();

Modified: chemistry/site/trunk/content/java/opencmis.mdtext
--- chemistry/site/trunk/content/java/opencmis.mdtext (original)
+++ chemistry/site/trunk/content/java/opencmis.mdtext Fri Mar 25 16:57:26 2011
@@ -11,7 +11,7 @@ different abstraction levels. It also in
 repository developers and client application developers.
 # Getting OpenCMIS
-You can get OpenCMIS from the [Download page](download.html).
+You can get OpenCMIS from the [download page](download.html).
 ## OpenCMIS releases

View raw message