org.modeshape.jcr.api

## Interface RepositoriesContainer

- All Known Implementing Classes:
    JcrRepositoriesContainer

      public interface RepositoriesContainer

  Interface which defines components acting as containers for one or more `Repository` instances. A repository container is an entity that can manage a number of repositories, each repository being identified by a name. It is also able to start/`shutdown()`/return the names of all the repositories it manages.

  This is meant to replace the "container aspect" of the current `RepositoryFactory` interface. `RepositoryFactory` should only be used for creating/obtaining a new repository instance, as defined in the `RepositoryFactory` contract.

  When looking for and initializing specific repositories, this will use a similar `Map` of named parameters as `RepositoryFactory` but with a more "loose semantic":
  - when a repository should be initialized for the first time, the `getRepository(String, java.util.Map)` should be called, where the map of parameters contains a parameter named `org.modeshape.jcr.URL` which has a `String` value representing either the path to a JSON configuration file or, if it uses the `jndi` protocol, the name under which the repository is bound in JNDI.
  - if a repository has already been initialized & started up as described above, the `getRepository(String, java.util.Map)` method can be called with a `null` or empty map, as the container already holds a reference to the repository.

  ## Getting a RepositoriesContainer instance

  In order to use this service, clients will need to use the ModeShape API via the standard `ServiceLoader` mechanism,

         Iterator containersIterator = ServiceLoader.load(RepositoriesContainer.class).iterator();
         if (!containersIterator.hasNext()) {
          // no implementations are found on the classpath, meaning the modeshape-jcr.jar has not been correctly loaded.
         }
         //there shouldn't be more than 1 container
         RepositoriesContainer repositoriesContainer = containersIterator.next();

  Since:
    3.4

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `REPOSITORY_NAME` The name of the key for the ModeShape JCR repository name in the parameter map.
    `static String` | `URL` The name of the key for the ModeShape JCR URL in the parameter map.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Repository` | `getRepository(String repositoryName, Map<?,?> parameters)` Return the JCR Repository with the supplied name and an optional map of parameters which can be used to initialize the repository.
    `Set<String>` | `getRepositoryNames(Map<?,?> parameters)` Returns the names of all the available repositories, using an optional map of parameters which may be used to initialize additional repositories, which will also be returned.
    `Future<Boolean>` | `shutdown()` Shutdown this engine to stop all repositories created by calls to `getRepository(String, java.util.Map)`, terminate any ongoing background operations (such as sequencing), and reclaim any resources that were acquired by the repositories.
    `boolean` | `shutdown(long timeout, TimeUnit unit)` Shutdown this engine to stop all repositories created by calls to `getRepository(String, java.util.Map)`, terminate any ongoing background operations (such as sequencing), and reclaim any resources that were acquired by the repositories.

- - ### Field Detail

    - #### URL

          static final String URL

      The name of the key for the ModeShape JCR URL in the parameter map.
      See Also:
        `RepositoryFactory.URL`, Constant Field Values

    - #### REPOSITORY_NAME

          static final String REPOSITORY_NAME

      The name of the key for the ModeShape JCR repository name in the parameter map. This can be used as an alternative to specifying the repository name as a URL parameter within the `URL`.
      See Also:
        `RepositoryFactory.REPOSITORY_NAME`, Constant Field Values

  - ### Method Detail

    - #### shutdown

          Future<Boolean> shutdown()

      Shutdown this engine to stop all repositories created by calls to `getRepository(String, java.util.Map)`, terminate any ongoing background operations (such as sequencing), and reclaim any resources that were acquired by the repositories. This method may be called multiple times, but only the first time has an effect.

      Invoking this method does not preclude creating new `Repository` instances with future calls to `getRepository(String, java.util.Map)`. Any caller using this method as part of an application shutdown process should take care to cease invocations of `getRepository(String, java.util.Map)` prior to invoking this method.

      This method returns immediately, even before the repositories have been shut down. However, the caller can simply call the `get()` method on the returned `Future` to block until all repositories have shut down. Note that the `Future.get(long, java.util.concurrent.TimeUnit)` method can be called to block for a maximum amount of time.

      Returns:
        a future that allows the caller to block until the engine is shutdown; any error during shutdown will be thrown when `getting` the repository from the future, where the exception is wrapped in a `ExecutionException`. The value returned from the future will always be true if the engine shutdown (or was not running), or false if the engine is still running.

    - #### shutdown

          boolean shutdown(long timeout,
                         TimeUnit unit)
                           throws InterruptedException

      Shutdown this engine to stop all repositories created by calls to `getRepository(String, java.util.Map)`, terminate any ongoing background operations (such as sequencing), and reclaim any resources that were acquired by the repositories. This method may be called multiple times, but only the first time has an effect.

      This method is equivalent to calling "`shutdown().get(timeout,unit)`" on this method.

      Invoking this method does not preclude creating new `Repository` instances with future calls to `getRepository(String, java.util.Map)`. Any caller using this method as part of an application shutdown process should take care to cease invocations of `getRepository(String, java.util.Map)` prior to invoking this method.

      This method returns immediately, even before the repositories have been shut down. However, the caller can simply call the `get()` method on the returned `Future` to block until all repositories have shut down. Note that the `Future.get(long, java.util.concurrent.TimeUnit)` method can be called to block for a maximum amount of time.

      Parameters:
        `timeout` - the maximum time per engine to allow for shutdown
        `unit` - the time unit of the timeout argument
      Returns:
        `true` if all engines completely shut down and `false` if the timeout elapsed before it was shut down completely
      Throws:
        `InterruptedException` - if interrupted while waiting

    - #### getRepositoryNames

          Set<String> getRepositoryNames(Map<?,?> parameters)
                                         throws RepositoryException

      Returns the names of all the available repositories, using an optional map of parameters which may be used to initialize additional repositories, which will also be returned.
      Parameters:
        `parameters` - map of string key/value pairs as repository arguments or `null` if none are provided
      Returns:
        the immutable set of repository names provided by this container; never `null`
      Throws:
        `RepositoryException` - if there is an error performing the lookup.
      See Also:
        `RepositoryFactory.getRepository(java.util.Map)`

    - #### getRepository

          Repository getRepository(String repositoryName,
                                 Map<?,?> parameters)
                                   throws RepositoryException

      Return the JCR Repository with the supplied name and an optional map of parameters which can be used to initialize the repository.
      Parameters:
        `repositoryName` - the name of the repository to return; may be `null` if, for example, the parameters map already contains this information.
        `parameters` - map of string key/value pairs as repository arguments. My be `null` if no configuration parameters exist.
      Returns:
        the repository with the given name or `null` if no repository is found
      Throws:
        `RepositoryException` - if there is an error communicating with the repository
      See Also:
        `RepositoryFactory.getRepository(java.util.Map)`

Copyright © 2008-2014 JBoss, a division of Red Hat. All Rights Reserved.