Package org.apache.sling.jcr.base

## Class AbstractSlingRepositoryManager

- java.lang.Object
- - org.apache.sling.jcr.base.AbstractSlingRepositoryManager

    @ProviderType
    public abstract class AbstractSlingRepositoryManager
    extends Object

The `AbstractSlingRepositoryManager` is the basis for controlling the JCR repository instances used by Sling. As a manager it starts and stops the actual repository instance, manages service registration and hands out `SlingRepository` instances to be used by the consumers.

This base class controls the livecycle of repository instance whereas implementations of this class provide actual integration into the runtime context. The livecycle of the repository instance is defined as follows:

To start the repository instance, the implementation calls the `start(BundleContext, String, boolean)`method which goes through the steps of instantiating the repository, setting things up, and registering the repository as an OSGi service:

1. `acquireRepository()`
2. `create(Bundle)`
3. `registerService()`

Earlier versions of this class had an additional `setup` method, whatever code was there can be moved to the `create` method.

If starting the repository fails, the method `stoppingOnError(String, Throwable)` will be called. By default the exception is logged as an error, but this can be customized by overwriting the method.

To stop the repository instance, the implementation calls the `stop()` method which goes through the steps of unregistering the OSGi service, tearing all special settings down and finally shutting down the repository:

1. `unregisterService(ServiceRegistration)`
2. `destroy(AbstractSlingRepository2)`
3. `disposeRepository(Repository)`

Instances of this class manage a single repository instance backing the OSGi service instances. Each consuming bundle, though, gets its own service instance backed by the single actual repository instance managed by this class.

Since:
  API version 2.3 (bundle version 2.2.2)
See Also:
  `AbstractSlingRepository2`

### Nested Class Summary

Nested Classes
`protected static class` `AbstractSlingRepositoryManager.Config` Configuration pojo to be passed to the `start(BundleContext, Config)` method.

### Constructor Summary

Constructors
`AbstractSlingRepositoryManager()`

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
`protected abstract javax.jcr.Repository` `acquireRepository()` Creates the backing JCR repository instances.
`protected boolean` `allowLoginAdministrativeForBundle​(org.osgi.framework.Bundle bundle)` Returns whether or not the provided bundle is allowed to use `SlingRepository.loginAdministrative(String)`.
`protected abstract AbstractSlingRepository2` `create​(org.osgi.framework.Bundle usingBundle)` Creates an instance of the `AbstractSlingRepository2` implementation for use by the given `usingBundle`.
`protected abstract void` `destroy​(AbstractSlingRepository2 repositoryServiceInstance)` Cleans up the given `AbstractSlingRepository2` instance previously created by the `create(Bundle)` method.
`protected abstract void` `disposeRepository​(javax.jcr.Repository repository)` Disposes off the given `repository`.
`String` `getDefaultWorkspace()` Returns the default workspace, which may be `null` meaning to use the repository provided default workspace.
`protected javax.jcr.Repository` `getRepository()` Returns the repository underlying this instance or `null` if no repository is currently being available.
`protected String[]` `getServiceRegistrationInterfaces()` Returns the service types to be used to register the repository service in `registerService()`.
`protected abstract Dictionary<String,​Object>` `getServiceRegistrationProperties()` Return the service registration properties to be used to register the repository service in `registerService()`.
`protected abstract org.apache.sling.serviceusermapping.ServiceUserMapper` `getServiceUserMapper()` Returns the `ServiceUserMapper` service to map the service name to a service user name.
`boolean` `isDisableLoginAdministrative()` Returns whether to disable the `SlingRepository.loginAdministrative` method or not.
`protected org.osgi.framework.ServiceRegistration` `registerService()` Registers this component as an OSGi service with the types provided by the `getServiceRegistrationInterfaces()` method and properties provided by the `getServiceRegistrationProperties()` method.
`protected boolean` `start​(org.osgi.framework.BundleContext bundleContext, String defaultWorkspace, boolean disableLoginAdministrative)` Deprecated. use `start(BundleContext, AbstractSlingRepositoryManager.Config)` instead.
`protected void` `start​(org.osgi.framework.BundleContext bundleContext, AbstractSlingRepositoryManager.Config config)` This method actually starts the backing repository instannce and registeres the repository service.
`protected void` `stop()`
`protected void` `stoppingOnError​(String message, Throwable t)` Called when the repository service cannot be initialized or registered because an exception occurred.
`protected void` `unregisterService​(org.osgi.framework.ServiceRegistration serviceRegistration)` Unregisters the service represented by the `serviceRegistration`.

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### AbstractSlingRepositoryManager

    public AbstractSlingRepositoryManager()

### Method Detail

#### getDefaultWorkspace

    public final String getDefaultWorkspace()

Returns the default workspace, which may be `null` meaning to use the repository provided default workspace.

Returns:
  the default workspace or `null` indicating the repository's default workspace is actually used.

#### isDisableLoginAdministrative

    public final boolean isDisableLoginAdministrative()

Returns whether to disable the `SlingRepository.loginAdministrative` method or not.

Returns:
  `true` if `SlingRepository.loginAdministrative` is disabled.

#### getServiceUserMapper

    protected abstract org.apache.sling.serviceusermapping.ServiceUserMapper getServiceUserMapper()

Returns the `ServiceUserMapper` service to map the service name to a service user name.

The `ServiceUserMapper` is used to implement the `AbstractSlingRepository2.loginService(String, String)` method used to replace the `AbstractSlingRepository2.loginAdministrative(String)` method. If this method returns `null` and hence the `ServiceUserMapperService` is not available, the `loginService` method is not able to login.

Returns:
  The `ServiceUserMapper` service or `null` if not available.
See Also:
  `AbstractSlingRepository2.loginService(String, String)`

#### allowLoginAdministrativeForBundle

    protected boolean allowLoginAdministrativeForBundle​(org.osgi.framework.Bundle bundle)

Returns whether or not the provided bundle is allowed to use `SlingRepository.loginAdministrative(String)`.

Parameters:
  `bundle` - The bundle requiring access to `loginAdministrative`
Returns:
  A boolean value indicating whether or not the bundle is allowed to use `loginAdministrative`.

#### acquireRepository

    protected abstract javax.jcr.Repository acquireRepository()

Creates the backing JCR repository instances. It is expected for this method to just start the repository.

This method does not throw any `Throwable` but instead just returns `null` if not repository is available. Any problems trying to acquire the repository must be caught and logged as appropriate.

Returns:
  The acquired JCR `Repository` or `null` if not repository can be acquired.
See Also:
  `start(BundleContext, String, boolean)`

#### registerService

    protected final org.osgi.framework.ServiceRegistration registerService()

Registers this component as an OSGi service with the types provided by the `getServiceRegistrationInterfaces()` method and properties provided by the `getServiceRegistrationProperties()` method.

The repository is actually registered as an OSGi `ServiceFactory` where the `create(Bundle)` method is called to create an actual `AbstractSlingRepository2` repository instance for a calling (using) bundle. When the bundle is done using the repository instance, the `destroy(AbstractSlingRepository2)` method is called to clean up.

Returns:
  The OSGi `ServiceRegistration` object representing the registered service.
See Also:
  `start(BundleContext, String, boolean)`, `getServiceRegistrationInterfaces()`, `getServiceRegistrationProperties()`, `create(Bundle)`, `destroy(AbstractSlingRepository2)`

#### getServiceRegistrationProperties

    protected abstract Dictionary<String,​Object> getServiceRegistrationProperties()

Return the service registration properties to be used to register the repository service in `registerService()`.

Returns:
  The service registration properties to be used to register the repository service in `registerService()`
See Also:
  `registerService()`

#### getServiceRegistrationInterfaces

    protected String[] getServiceRegistrationInterfaces()

Returns the service types to be used to register the repository service in `registerService()`. All interfaces returned must be accessible to the class loader of the class of this instance.

This method may be overwritten to return additional types but the types returned from this base implementation, `SlingRepository` and `Repository`, must always be included.

Returns:
  The service types to be used to register the repository service in `registerService()`
See Also:
  `registerService()`

#### create

    protected abstract AbstractSlingRepository2 create​(org.osgi.framework.Bundle usingBundle)

Creates an instance of the `AbstractSlingRepository2` implementation for use by the given `usingBundle`.

This method is called when the repository service is requested from within the using bundle for the first time.

This method is expected to return a new instance on every call.

Parameters:
  `usingBundle` - The bundle providing from which the repository is requested.
Returns:
  The `AbstractSlingRepository2` implementation instance to be used by the `usingBundle`.
See Also:
  `registerService()`

#### destroy

    protected abstract void destroy​(AbstractSlingRepository2 repositoryServiceInstance)

Cleans up the given `AbstractSlingRepository2` instance previously created by the `create(Bundle)` method.

Parameters:
  `repositoryServiceInstance` - The `AbstractSlingRepository2` istance to cleanup.
See Also:
  `registerService()`

#### getRepository

    protected final javax.jcr.Repository getRepository()

Returns the repository underlying this instance or `null` if no repository is currently being available.

Returns:
  The repository

#### unregisterService

    protected final void unregisterService​(org.osgi.framework.ServiceRegistration serviceRegistration)

Unregisters the service represented by the `serviceRegistration`.

Parameters:
  `serviceRegistration` - The service to unregister

#### disposeRepository

    protected abstract void disposeRepository​(javax.jcr.Repository repository)

Disposes off the given `repository`.

Parameters:
  `repository` - The repository to be disposed off which is the same as the one returned from `acquireRepository()`.

#### stoppingOnError

    protected void stoppingOnError​(String message,
                                   Throwable t)

Called when the repository service cannot be initialized or registered because an exception occurred.

This default implementation logs the exception as an error.

Parameters:
  `message` - failure details.
  `t` - the exception.

#### start

    @Deprecated
    protected final boolean start​(org.osgi.framework.BundleContext bundleContext,
                                  String defaultWorkspace,
                                  boolean disableLoginAdministrative)

Deprecated.
use `start(BundleContext, AbstractSlingRepositoryManager.Config)` instead.
This method was deprecated with the introduction of asynchronous repository registration. With asynchronous registration a boolean return value can no longer be guaranteed, as registration may happen after the method returns.

Instead a `ServiceListener` for `SlingRepository` may be registered to get informed about its successful registration.

Parameters:
  `bundleContext` - The `BundleContext` to register the repository service (and optionally more services required to operate the repository)
  `defaultWorkspace` - The name of the default workspace to use to login. This may be `null` to have the actual repository instance define its own default
  `disableLoginAdministrative` - Whether to disable the `SlingRepository.loginAdministrative` method or not.
Returns:
  `true` if the repository has been started and the service is registered; `false` if the service has not been registered, which may indicate that startup was unsuccessful OR that it is happening asynchronously. A more reliable way to determin availability of the `SlingRepository` as a service is using a `ServiceListener`.

#### start

    protected final void start​(org.osgi.framework.BundleContext bundleContext,
                               AbstractSlingRepositoryManager.Config config)

This method actually starts the backing repository instannce and registeres the repository service.

Multiple subsequent calls to this method without calling `stop()` first have no effect.

Parameters:
  `bundleContext` - The `BundleContext` to register the repository service (and optionally more services required to operate the repository)
  `config` - The configuration to apply to this instance.

#### stop

    protected final void stop()