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/03/25 17:57:27 UTC
svn commit: r1085470 - in /chemistry/site/trunk/content: ./ java/
java/developing/ java/developing/client/ java/examples/
Author: fmui
Date: Fri Mar 25 16:57:26 2011
New Revision: 1085470
URL: http://svn.apache.org/viewvc?rev=1085470&view=rev
Log:
a bit more OpenCMIS client documentation
Modified:
chemistry/site/trunk/content/index.mdtext
chemistry/site/trunk/content/java/developing/client/dev-client-overview.mdtext
chemistry/site/trunk/content/java/developing/dev-session-parameters.mdtext
chemistry/site/trunk/content/java/developing/index.mdtext
chemistry/site/trunk/content/java/examples/example-create-session.mdtext
chemistry/site/trunk/content/java/opencmis.mdtext
Modified: chemistry/site/trunk/content/index.mdtext
URL: http://svn.apache.org/viewvc/chemistry/site/trunk/content/index.mdtext?rev=1085470&r1=1085469&r2=1085470&view=diff
==============================================================================
--- 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)](http://docs.oasis-open.org/cmis/CMIS/v1.0/cmis-spec-v1.0.html)
- 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:
-dev@chemistry.apache.org
+[dev@chemistry.apache.org](http://mail-archives.apache.org/mod_mbox/chemistry-dev/)
-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
URL: http://svn.apache.org/viewvc/chemistry/site/trunk/content/java/developing/client/dev-client-overview.mdtext?rev=1085470&r1=1085469&r2=1085470&view=diff
==============================================================================
--- 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](http://docs.oasis-open.org/cmis/CMIS/v1.0/cmis-spec-v1.0.html). 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 project.
-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
URL: http://svn.apache.org/viewvc/chemistry/site/trunk/content/java/developing/dev-session-parameters.mdtext?rev=1085470&r1=1085469&r2=1085470&view=diff
==============================================================================
--- 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
org.apache.chemistry.opencmis.session.repository.id|REPOSITORY_ID|Repository id|repository id|createSession(): yes<br/>getRepositories(): no
-org.apache.chemistry.opencmis.user|USER|User name<br/>(used by standard authentication provider)|string
-org.apache.chemistry.opencmis.password|PASSWORD|Password<br/>(used by standard authentication provider)|string
+org.apache.chemistry.opencmis.user|USER|User name<br/>(used by the standard authentication provider)|string
+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
URL: http://svn.apache.org/viewvc/chemistry/site/trunk/content/java/developing/index.mdtext?rev=1085470&r1=1085469&r2=1085470&view=diff
==============================================================================
--- 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
URL: http://svn.apache.org/viewvc/chemistry/site/trunk/content/java/examples/example-create-session.mdtext?rev=1085470&r1=1085469&r2=1085470&view=diff
==============================================================================
--- 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 2011
@@ -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
URL: http://svn.apache.org/viewvc/chemistry/site/trunk/content/java/opencmis.mdtext?rev=1085470&r1=1085469&r2=1085470&view=diff
==============================================================================
--- 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