Apache Jackrabbit : ApacheSling SlingGuideRepositoryUse

Created by ASF Infrabot on May 20, 2019

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 Jackrabbit Index Filters.