jackrabbit-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Jackrabbit Wiki] Update of "ApacheSling/SlingGuideRepositoryUse" by FelixMeschberger
Date Tue, 10 Jul 2007 09:02:58 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Jackrabbit Wiki" for change notification.

The following page has been changed by FelixMeschberger:
http://wiki.apache.org/jackrabbit/ApacheSling/SlingGuideRepositoryUse

The comment on the change is:
Creation

New page:
= How to access JCR Repositories with Sling =

Sling provides a number of bundles to make using a JCR Repository easy:

 jackrabbit-api:: Provides JCR and Jackrabbit API interfaces and classes as well as the Jackrabbit
commons library classes. Finally, this bundle implements the core for session pooling, which
is used by the jackrabbit-server and jackrabbit-client bundles.
 jackrabbit-server:: This bundle supports running embedded Jackrabbit repositories using the
default persistence manager. Any repositories instantiated by this bundle may optionally be
registered with an RMI registry and a JNDI context.
 jackrabbit-client:: This bundle supports accessing a repository through RMI or JNDI.
 jackrabbit-text-extractors:: Add support to extract text for indexing for the workspace indexer.


This page contains short descriptions on how to use each bundle.



== Jackrabbit API and Commons ==

The ''Jackrabbit API and Commons'' ({{{org.apache.sling.jackrabbit-api}}}) bundle provides
the following functionality:

   * Exports JCR API, Version 1.0
   * Export Jackrabbit API, currently Version 1.3
   * Exports the {{{SlingRepository}}} interface providing configurable default workspace
and admin session
   * Implements Session Pooling and provides an abstract implementation of the {{{SlingRepository}}}
interface with Session Pooling support

Bundles providing access to repositories register an OSGi service with the name {{{javax.jcr.Repository}}}.
If the actual repository implements more interfaces, such as a Jackrabbit repository or an
extension of the {{{AbstractSlingRepository}}}, all implemented interfaces should be also
listed as service names.



== Embedded Jackrabbit Repository ==

The ''Jackrabbit Embedded Repository'' ({{{org.apache.sling.jackrabbit-server}}}) bundle provides
the following functionality:

   * Contains and exports all of the Jackrabbit Core library
   * Implements the {{{!SlingRepository}}} interface backed by a Jackrabbit repository
   * Registers a OSGi Component Factory to create repository instances on demand
   * Registers repository instances as OSGi services as {{{javax.jcr.Repository}}}, {{{org.apache.jackrabbit.api.JackrabbitRepository}}},
{{{org.apache.sling.jcr.SlingRepository}}}
   * Contains enough third-party libraries pertinent to Jackrabbit to run a Jackrabbit with
the default persistence manager
   * Supports registration of repositories with an RMI Registry and a JNDI context.



=== Configuration ===


Configuration of the repositories started by this bundle is split into two parts: (1) configuration
of the OSGi service mainly configuring the Session Pool, user names and passwords for administrative
and anonymous sessions, RMI/JNDI registration information; and (2) repository configuration
itself contained in a traditional {{{repository.xml}}} file.

**NOTE**: For this bundle to be operative, the OSGi container must provide the OSGi Configuration
Admin Service, from which the configuration is retrieved and which is used to persist the
configuration objects.



==== OSGi Service Configuration ====

OSGi service configuration is managed through the OSGi Configuration Admin Service and supports
the following properties:

|| '''Name''' || '''Type''' || '''Default''' || '''Description''' ||
|| {{{home}}} || String || - || The directory in which to launch the Jackrabbit repository.
This property is required and has no default value. If this path is relative, it is resolved
relative to the path set in the {{{sling.home}}} framework property available through the
bundle context. ||
|| {{{config}}} || String || - || The name of the repository configuration file. This property
is required and has no default value. If this path is relative, it is resolved relative to
the path set in the {{{sling.home}}} property. If this name is an URL, it must be a valid
URL which may be connected to and read from. ||
|| {{{autostart}}} || boolean || {{{true}}} || Whether to start the repository immediately
({{{true}}}) or on demand when first accessed. As the object created for the configuration
and registered as an OSGi service is actually a facade to the real repository object, the
start of the repository may be delayed until actually accessed. ||
|| {{{defaultWorkspace}}} || String || {{{default}}} || The name of the workspace to which
sessions are created if no workspace name is supplied to the login method used. If this workspace
does not exist, it will automatically be created through an administrative session using the
user name and password configured. ||
|| {{{admin.name}}} || String || {{{admin}}} || The name used to create administrative sessions
implementing the {{{SlingRepository.loginAdministrative(String)}}} method. The Sling framework
is using administrative sesions for all sorts of task requiring administrative privileges
such as creating the configured {{{defaultWorkspace}}} if required. Therefore this user has
to have full access to the repository and all its workspace(s). ||
|| {{{admin.password}}} || String || {{{admin}}} || The password used to create administrative
sesions. ||
|| {{{anonymous.name}}} || String || {{{anonymous}}} || The name used to create anonymous
sessions, which are created when any of the {{{Repository.login}}} methods is called without
a {{{Credentials}}} object. The Sling framework mainly uses anonymous sessions to handle unauthenticated
requests. If this property is not set or set to a name not accepted by the repository, unauthenticated
requests will of course fail. ||
|| {{{anonymous.password}}} || String || {{{anonymous}}} || The password used to create anonymous
sessions.||
|| {{{pool.maxActive}}} || int || -1 || The maximum number of sessions per user allowed to
be active at a given moment. If this property is set to a value larger than zero, only the
given number of sesions may be logged in at the same time. Further requests first wait for
a session to become available and fail if no session becomes available. If this property is
set to a negative value - the default value of this property is -1 - the number of active
sesions is virtually unlimited. ||
|| {{{pool.maxActiveWait}}} || int || 1 || The number of seconds to wait for a session to
become available if the maximum number of active sessions has been reached. If no session
becomes available within this timeframe the login attempt fails with a {{{org.apache.sling.jcr.TooManySessionsException}}}.
||
|| {{{pool.maxIdle}}} || int || 10 || The number of sessions to keep in the session pool.
If a user tries to login, the session pool is first consulted for an existing session. Only
if no session exists, a new session is created. If the user finally logs out, the session
is put back into the pool, unless the number of sessions idling in the pool has already reached
this number. ||
|| {{{name}}} || String || - || The name to use to register the repository with a JNDI context
and the RMI registry. If this property is not set, the repository is not registered in both
the JNDI context and the RMI registry. See below for more information. ||


==== Initial Configuration ====

When the bundle is launched, the bundle activator checks to see for at least one concrete
configuration object for the repository component. If no such configuration object exists,
one is created to ensure that a repository is available out of the box.

If the activator finds an OSGI configuration object, nothing needs to be done. Otherwise a
new configuration object with default configuration with the {{{home}}}, {{{config}}} and
{{{name}}} properties set as listed below is created and stored with the Configuration Admin
Service. Storing the configuration results in having the repository launched as the Configuration
Admin Service provides this configuration object to the OSGi component factory which in turn
then launches the repository. Said configuration properties are defined as follows:

|| '''Name''' || '''Value''' ||
|| {{{home}}} || {{{${sling.home}/jackrabbit}}} ||
|| {{{config}}} || {{{${sling.home}/repository.xml}}} ||
|| {{{name}}} || {{{jackrabbit.repository}}} ||

The Jackrabbit Repository Configuration file in the Sling home directory is copied from within
the Jackrabbit Embedded Repository Bundle, if it does no exist yet. Any existing {{{repository.xml}}}
file is not overwritten.



==== RMI Registration ====

Registration with an RMI registry is handled with a separate component, which listens for
OSGi services of the name {{{javax.jcr.Repository}}} to be registered. Upon such a registration,
the RMI registrar checks the service properties for a {{{name}}} property. If the property
is found, that name is used to bind the repository with the RMI registry. When the repository
is unregistered it is also unbound from the RMI registry.

The RMI registrar is configured with the port number at which the RMI registry is to be expected.
If an RMI registry is already running at this port, this registry is used. Otherwise a registry
is created to listen on the configured port. If another RMI registry is already running in
the same Java VM (but on a different port), the RMI registrar cannot create another RMI registry
(only one RMI registry per Java VM is possible), the RMI registrar is not operational and
repositories will not be registered with RMI.

When the RMI registrar is terminated and has created its own RMI registry, the registry is
destroyed. Otherwise the registry is left alone.

'''Configuration'''

|| '''Name''' || '''Type''' || '''Default''' || '''Description''' ||
|| {{{port}}} || Integer || 1099 || The port at which to create (or expect) the registry.
If no registry is available on this port or can be created to listen on this port, the RMI
registrar remains inactive and will not register repositories at all. ||


==== JNDI Registration ====

Registration with a JNDI context is handled with a separate component, which listens for OSGi
services of the name {{{javax.jcr.Repository}}} to be registered. Upon such a registration,
the JNDI registrar checks the service properties for a {{{name}}} property. If the property
is found, that name is used to bind the repository with the JNDI context. When the repository
service is unregistered it is also unbound from the JNDI context.

The JNDI context is managed by the JNDI registrar component through its configuration. The
registrar uses the platform to access a JNDI initial context. If the JNDI context is to be
visible outside the OSGi framework but in the same Java VM instance (for example in a different
Web Application if the Sling is started as a web application), the JNDI Initial Context class
''must'' be loaded through a class loader common to the OSGi framework and the user outside
of the framework.

The default configuration of the JNDI registrar uses the {{{org.apache.jackrabbit.core.jndi.provider.DummyInitialContextFactory}}}
class as its initial context factory. If the initial context cannot be created, the JNDI registrar
remains inactive and will register repositories with JNDI.

*Configuration*

|| '''Name''' || '''Type''' || '''Default''' || '''Description''' ||
|| {{{java.naming.factory.initial}}} || String || {{{org.apache.jackrabbit.core.jndi.provider.DummyInitialContextFactory}}}
|| The fully qualified name of the JNDI Initial Context factory. ||
|| {{{java.naming.provider.url}}} || String || {{{http://www.apache.org/jackrabbit}}} || The
JNDI Provider URL. ||



===== External Clients =====

If the context needs to be shared with clients outside the OSGi framework (but inside the
same Java VM instance), the class referred to in the {{{java.naming.factory.initial}}} property
must be available in a common class loader. Additionally, the JCR and Jackrabbit APIs must
also be available from the same location. Finally, all the Java packages (the JNDI InitialContextFactory
class as well as the JCR and Jackrabbit APIs) must be made available to the OSGi framework
bundles.

To enable such class sharing, the respective Java packages must be declared in the {{{sling.properties}}}
file as part of the {{{org.osgi.framework.bootdelegation}}} property. The Sling (and derived)
Web Applications provides support to setup this property depending on the environment it is
running in: If the {{{javax.jcr.Repository}}} class is visible in the Web Application, it
is assumed that the JCR and Jackrabbit API classes are contained in a shared class loader
and hence the respective packages are added to the {{{bootdelegation}}} property automatically.

Note, that you may well place the ''Jackrabbit API and Commons'' ({{{org.apache.sling.jackrabbit-api}}})
bundle jar file into the shared class loader, as this file contains all the required packages
and classes. Just be sure, to list all exports of the bundle in the {{{org.osgi.framework.bootdelegation}}}
framework property (without the ''uses'' clauses).



== External Jackrabbit Repository ==

Accessing a JCR Repository running outside of the OSGi framework is supported by the ''Jackrabbit
Repository Accessor'' ({{{org.apache.sling.jackrabbit-client}}}) bundle. This bundle provides
a single factory component registering Repository services as they are found from JNDI or
RMI. Each configuration tries to access a repository.


==== OSGi Service Configuration ====

OSGi service configuration is managed through the OSGi Configuration Admin Service and supports
the following properties:

|| '''Name''' || '''Type''' || '''Default''' || '''Description''' ||
|| {{{defaultWorkspace}}} || String || {{{default}}} || The name of the workspace to which
sessions are created if no workspace name is supplied to the login method used. If this workspace
does not exist, it will automatically be created through an administrative session using the
user name and password configured. ||
|| {{{admin.name}}} || String || {{{admin}}} || The name used to create administrative sessions
implementing the {{{SlingRepository.loginAdministrative(String)}}} method. The Sling framework
is using administrative sesions for all sorts of task requiring administrative privileges
such as creating the configured {{{defaultWorkspace}}} if required. Therefore this user has
to have full access to the repository and all its workspace(s). ||
|| {{{admin.password}}} || String || {{{admin}}} || The password used to create administrative
sesions. ||
|| {{{anonymous.name}}} || String || {{{anonymous}}} || The name used to create anonymous
sessions, which are created when any of the {{{Repository.login}}} methods is called without
a {{{Credentials}}} object. The Sling framework mainly uses anonymous sessions to handle unauthenticated
requests. If this property is not set or set to a name not accepted by the repository, unauthenticated
requests will of course fail. ||
|| {{{anonymous.password}}} || String || {{{anonymous}}} || The password used to create anonymous
sessions.||
|| {{{pool.maxActive}}} || int || -1 || The maximum number of sessions per user allowed to
be active at a given moment. If this property is set to a value larger than zero, only the
given number of sesions may be logged in at the same time. Further requests first wait for
a session to become available and fail if no session becomes available. If this property is
set to a negative value - the default value of this property is -1 - the number of active
sesions is virtually unlimited. ||
|| {{{pool.maxActiveWait}}} || int || 1 || The number of seconds to wait for a session to
become available if the maximum number of active sessions has been reached. If no session
becomes available within this timeframe the login attempt fails with a {{{org.apache.sling.jcr.TooManySessionsException}}}.
||
|| {{{pool.maxIdle}}} || int || 10 || The number of sessions to keep in the session pool.
If a user tries to login, the session pool is first consulted for an existing session. Only
if no session exists, a new session is created. If the user finally logs out, the session
is put back into the pool, unless the number of sessions idling in the pool has already reached
this number. ||
|| {{{name}}} || String || {{{jackrabbit.repository}}} || The name of the repository to access
in either the JNDI context or the RMI registry. If the repository is accessible through JNDI,
this property must contain the full RMI URL of the form ==~//host~port/name==. ||
|| {{{java.naming.factory.initial}}} || String || {{{org.apache.jackrabbit.core.jndi.provider.DummyInitialContextFactory}}}
|| The fully qualified name of the JNDI Initial Context factory. This property is only needed
in case the repository is to be accessed through JNDI. Otherwise this property is ignored.
||
|| {{{java.naming.provider.url}}} || String || {{{http://www.apache.org/jackrabbit}}} || The
JNDI Provider URL. This property is only needed in case the repository is to be accessed through
JNDI. Otherwise this property is ignored. ||


===== Accessing a Repository through JNDI =====

If the existing repository has to be accessed through JNDI, the Initial Context classes must
be shared with the provider of the repository. In the case of running Sling as a Web Application,
the JNDI Initial Context class must be loaded from a shared class loader. Likewise, all the
JCR and Jackrabbit API classes must also be loaded from a shared class loader. Otherwise the
JNDI context cannot be accessed or the repository found may not be of the correct Java type.

To enable such class sharing, the respective Java packages must be declared in the {{{sling.properties}}}
file as part of the {{{org.osgi.framework.bootdelegation}}} property. The Sling (and derived)
Web Applications provides support to setup this property depending on the environment it is
running in: If the {{{javax.jcr.Repository}}} class is visible in the Web Application, it
is assumed that the JCR and Jackrabbit API classes are contained in a shared class loader
and hence the respective packages are added to the {{{bootdelegation}}} property automatically.


===== Accessing a Repository through RMI =====

If the existing repository has to be accessed through RMI, no special precautions must be
taken as the RMI stubs to access the repository are contained in the bundle and are thus used.
To access the repository, the full RMI URL of the form {{{//host[:port]/name}}} (eg. {{{//localhost/jackrabbit.repository}}})
is just configured as the Repository Name.



== Jackrabbit Text Extractors ==

Jackrabbit Text Extractors extend the Jackrabbit Repository based search indexing with support
for various office document formats such as Microsoft Word, Microsoft Excel, PDF, OpenOffice
etc. To use these extractors, install the ''jackrabbit-text-extractors'' bundle ({{{org.apache.sling.jackrabbit-text-extractors}}})
and configure the text extractor class names as the value (comma-separated list) of the {{{textFilterClasses}}}
parameter in the {{{SearchIndex}}} element of each workspace, which is to be supported by
these extractors.

For more information on the Jackrabbit Text Extractors refer to [http://jackrabbit.apache.org/doc/components/index-filters.html
Jackrabbit Index Filters].

Mime
View raw message