----------------------
                       Jackrabbit JCR-RMI 1.5
                       ----------------------

~~ Licensed to the Apache Software Foundation (ASF) under one or more
~~ contributor license agreements.  See the NOTICE file distributed with
~~ this work for additional information regarding copyright ownership.
~~ The ASF licenses this file to You under the Apache License, Version 2.0
~~ (the "License"); you may not use this file except in compliance with
~~ the License.  You may obtain a copy of the License at
~~
~~     http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing, software
~~ distributed under the License is distributed on an "AS IS" BASIS,
~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~~ See the License for the specific language governing permissions and
~~ limitations under the License.

    Version 1.5.0 of the Apache Jackrabbit JCR-RMI component was released
    as a component of the larger Apache Jackrabbit distribution.

    * {{{http://jackrabbit.apache.org/downloads.html}Download}} JCR-RMI 1.5.0 as a part of the bigger Apache Jackrabbit 1.5.x releases

    * {{{https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&&pid=10591&component=12310820&fixfor=12312920&resolution=1&sorter/field=priority&sorter/order=DESC}Changes}} in this release

    * {{{http://jackrabbit.apache.org/api/1.5/}API documentation}}, see the org.apache.jackrabbit.rmi packages

Setting up a remote repository

    Setting up the server part of the JCR-RMI layer is quite straightforward.
    After instantiating a local JCR repository you need to wrap it into
    a remote adapter and create an RMI binding for the repository. A variation
    of the following code is usually all that is needed in addition to
    the standard RMI setup (starting rmiregistry, etc.):

----
Repository repository = ...; // The local repository
String name = ...; // The RMI URL for the repository

RemoteAdapterFactory factory = new ServerAdapterFactory();
RemoteRepository remote = factory.getRemoteRepository(repository);
Naming.bind(name, remote);  // Make the RMI binding using java.rmi.Naming
----

Accessing a remote repository

    The ClientRepositoryFactory class provides a convenient mechanism for
    looking up a remote JCR-RMI repository. The factory can be used either
    directly or as a JNDI object factory.

    The following example shows how to use the ClientRepositoryFactory
    directly:

----
String name = ...; // The RMI URL of the repository

ClientRepositoryFactory factory = new ClientRepositoryFactory();
Repository repository = factory.getRepository(name);
----

    The ClientRepositoryFactory can also be used via JNDI. The following
    example settings and code demonstrate how to configure and use the
    transparent JCR-RMI layer in a Tomcat 5.5 web application:

    context.xml:

----
<Resource name="jcr/Repository" auth="Container"
          type="javax.jcr.Repository"
          factory="org.apache.jackrabbit.rmi.client.ClientRepositoryFactory"
          url="..."/>
----

    web.xml:

----
<resource-env-ref>
  <description>The external content repository</description>
  <resource-env-ref-name>jcr/Repository</resource-env-ref-name>
  <resource-env-ref-type>javac.jcr.Repository</resource-env-ref-type>
</resource-env-ref>
----

    SomeServlet.java:

----
Context initial = new InitialContext();
Context context = (Context) initial.lookup("java:comp/env");
Repository repository = (Repository) context.lookup("jcr/Repository");
----

    Note that in the example above only the context.xml configuration file
    contains a direct references to the JCR-RMI layer. All other parts of
    the web application can be implemented using the standard JCR interfaces.