org.modeshape.jcr.api

## Interface RepositoryFactory

- All Superinterfaces:
    Repositories, RepositoryFactory

      public interface RepositoryFactory
      extends RepositoryFactory, Repositories

  An extension to the standard `RepositoryFactory` interface, with ModeShape-specific constants and additional `shutdown()` methods.

  ModeShape's RepositoryFactory implementation looks for two parameters:

  - `org.modeshape.jcr.URL` - This parameter specifies the URL of the configuration file for the repository to be used.
  - `org.modeshape.jcr.RepositoryName` - This parameter specifies the name of the repository that is to be used.
  Often, both properties will be used, resulting in ModeShape's factory using this logic:
  1. Look for an already-deployed repository with the name given by `org.modeshape.jcr.RepositoryName`. If one is found, then return that Repository instance.
  2. Look for the repository's configuration file at the URL given by `org.modeshape.jcr.URL`. If the file had already been loaded, find the repository and return it; otherwise attempt to load the file, deploy the repository, and return the Repository instance.

  But strictly speaking, only the `org.modeshape.jcr.api.URL` parameter is required, since the configuration file contains the name of the repository. So why supply the `org.modeshape.jcr.RepositoryName` parameter? Because ModeShape's `RepositoryFactory.getRepository(Map)` method can look up an existing repository by name faster than it can load the configuration file. In other words, using both parameters makes for a faster operation.

  ## Use the Standard JCR API

  The best way for your application to use the RepositoryFactory is to use only the JCR API, and load the properties from a file. This way, only the file has implementation-specific information, while your application uses only the standard JCR API:

       Properties parameters = new Properties();
       parameters.load(...); // Load from a stream or reader

       Repository repository = null;
       for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {
           repository = factory.getRepository(parameters);
           if (repository != null) break;
       }

  ## Use the ModeShape constants

  If you'd rather your application programmatically create the parameters to pass to JCR's RepositoryFactory, and your application is already dependent upon the ModeShape public API, you can use the constants in this interface to build your parameters.

       String configUrl = "file://path/to/configFile.json"; // URL that points to the repository's configuration file
       String repoName = "MyRepository"; // Name of the repository (this is optional)

       Map<String, String> parameters = new HashMap<String, String>();
       parameters.put(org.modeshape.jcr.api.RepositoryFactory.URL, configUrl);
       parameters.put(org.modeshape.jcr.api.RepositoryFactory.RepositoryName, repoName);

       Repository repository = null;
       for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {
           repository = factory.getRepository(parameters);
           if (repository != null) break;
       }

- - ### 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)` Deprecated. since 3.4, this method should not be used. Code using it should change to use `RepositoriesContainer` instead
    `Set<String>` | `getRepositoryNames()` Deprecated. since 3.4, this method should not be used. Code using it should change to use `RepositoriesContainer` instead
    `Future<Boolean>` | `shutdown()` Deprecated. since 3.4, this method should not be used. Code using it should change to use `RepositoriesContainer` instead
    `boolean` | `shutdown(long timeout, TimeUnit unit)` Deprecated. since 3.4, this method should not be used. Code using it should change to use `RepositoriesContainer` instead

    - ### Methods inherited from interface javax.jcr.RepositoryFactory

      `getRepository`

- - ### Field Detail

    - #### URL

          static final String URL

      The name of the key for the ModeShape JCR URL in the parameter map.

      For example, define a URL that points to the configuration file for your repository:

           \// Define a
           String configUrl = "file://path/to/configFile.xml?repositoryName=myRepository"; // URL that points to your configuration file

           Map<String, String> parameters = new HashMap<String, String>();
           parameters.put(org.modeshape.jcr.api.RepositoryFactory.URL, configUrl);

           Repository repository = null;
           for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {
               repository = factory.getRepository(parameters);
               if (repository != null) break;
           }

      See Also:
        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`.

      For example:

           String configUrl = "file://path/to/configFile.json"; // URL that points to your configuration file
           String repoName = "myRepository"; // Name of your repository defined within the configuration file

           Map<String, String> parameters = new HashMap<String, String>();
           parameters.put(org.modeshape.jcr.api.RepositoryFactory.URL, configUrl);
           parameters.put(org.modeshape.jcr.api.RepositoryFactory.REPOSITORY_NAME, repoName);

           Repository repository = null;
           for (RepositoryFactory factory : ServiceLoader.load(RepositoryFactory.class)) {
               repository = factory.getRepository(parameters);
               if (repository != null) break;
           }

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### shutdown

          @Deprecated
          Future<Boolean> shutdown()

      Deprecated. since 3.4, this method should not be used. Code using it should change to use `RepositoriesContainer` instead
      Shutdown this engine to stop all repositories created by calls to `RepositoryFactory.getRepository(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 `RepositoryFactory.getRepository(Map)`. Any caller using this method as part of an application shutdown process should take care to cease invocations of `RepositoryFactory.getRepository(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, 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

          @Deprecated
          boolean shutdown(long timeout,
                                    TimeUnit unit)
                           throws InterruptedException

      Deprecated. since 3.4, this method should not be used. Code using it should change to use `RepositoriesContainer` instead
      Shutdown this engine to stop all repositories created by calls to `RepositoryFactory.getRepository(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 `RepositoryFactory.getRepository(Map)`. Any caller using this method as part of an application shutdown process should take care to cease invocations of `RepositoryFactory.getRepository(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, 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

          @Deprecated
          Set<String> getRepositoryNames()

      Deprecated. since 3.4, this method should not be used. Code using it should change to use `RepositoriesContainer` instead
      Description copied from interface: `Repositories`
      Get the names of the available repositories.
      Specified by:
        `getRepositoryNames` in interface `Repositories`
      Returns:
        the immutable set of repository names provided by this server; never null

    - #### getRepository

          @Deprecated
          Repository getRepository(String repositoryName)
                                   throws RepositoryException

      Deprecated. since 3.4, this method should not be used. Code using it should change to use `RepositoriesContainer` instead
      Description copied from interface: `Repositories`
      Return the JCR Repository with the supplied name.
      Specified by:
        `getRepository` in interface `Repositories`
      Parameters:
        `repositoryName` - the name of the repository to return; may not be null
      Returns:
        the repository with the given name; never null
      Throws:
        `RepositoryException` - if no repository exists with the given name or there is an error communicating with the repository

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