Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.modeshape.jcr.api
Interface RepositoryFactory

All Superinterfaces:
  RepositoryFactory

    public interface RepositoryFactory

extends RepositoryFactory

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 ModeShape engine with an optional "`repositoryName`" URL parameter specifying which of the repository defined in the configuration file should be used. Alternatively, if the URL begins with "`jndi:`", the object in the JNDI name will be looked up, and returned if it is a `Repository` instance or used to find the Repository instance if the JNDI object is the ModeShape engine.
- `org.modeshape.jcr.RepositoryName` - This parameter specifies the name of the repository that is to be used, and that is an alternative to the "`repositoryName` URL parameter.

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, start the engine, and find the Repository instance with the given name.

## 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 parameter.

The preferred approach is to specify the location of the ModeShape configuration file and the name of the repository using separate parameters:

     String configUrl = "file://path/to/configFile.xml"; // URL that points to ModeShape's configuration file
     String repoName = "MyRepository"; // Name of the repository

     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;
     }

Note, however, that the repository name could have been specified with a URL parameter:

     String configUrl = "file://path/to/configFile.xml?repositoryName=MyRepository";

     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;
     }

Field Summary
`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
`Repositories` | `getRepositories(String jcrUrl)` Returns the `Repositories` instance referenced by the `jcrUrl` parameter.
`void` | `shutdown()` Begin the shutdown process for all the `JcrEngine JcrEngines` created by calls to `RepositoryFactory.getRepository(Map)`.
`boolean` | `shutdown(long timeout, TimeUnit unit)` Begin the shutdown process for all the `JcrEngine JcrEngines` created by calls to `RepositoryFactory.getRepository(Map)`.

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:

       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.xml"; // 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

    void shutdown()

  Begin the shutdown process for all the `JcrEngine JcrEngines` created by calls to `RepositoryFactory.getRepository(Map)`.

  Calling `#getRepository(Map)` with a file-based URL parameter causes a new `JcrEngine` to be instantiated and started. Any `JcrEngine` created in this manner must be stored by the `RepositoryFactory` implementation. Invoking this method iteratively invokes the `shutdown()` method on each `JcrEngine`.

  This method merely initiates the shutdown process for each `JcrEngine`. There is no guarantee that the shutdown process will have completed prior to this method returning. The `shutdown(long, TimeUnit)` method provides the ability to wait until all engines are shutdown or the given time elapses.

  Invoking this method does not preclude creating new `JcrEngines` 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.

### shutdown

    boolean shutdown(long timeout,
                     TimeUnit unit)
                     throws InterruptedException

  Begin the shutdown process for all the `JcrEngine JcrEngines` created by calls to `RepositoryFactory.getRepository(Map)`.

  Calling `#getRepository(Map)` with a file-based URL parameter causes a new `JcrEngine` to be instantiated and started. Any `JcrEngine` created in this manner must be stored by the `RepositoryFactory` implementation. Invoking this method iteratively invokes the `shutdown()` method on each `JcrEngine` and then iteratively invokes the `awaitTermination(long, TimeUnit)` method to await termination.

  Although this method initiates the shutdown process for each `JcrEngine` and invokes the `awaitTermination` method, there is still no guarantee that the shutdown process will have completed prior to this method returning. It is possible for the time required to shutdown one or more of the engines to exceed the provided time window.

  Invoking this method does not preclude creating new `JcrEngines` 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.

  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

### getRepositories

    Repositories getRepositories(String jcrUrl)

  Returns the `Repositories` instance referenced by the `jcrUrl` parameter.

  If the `jcrUrl` parameter contains a valid, ModeShape-compatible URL for a `Repositories` instance that has not yet been started, that `Repositories instance` will be created and started as a side effect of this method.

  Parameters:
    `jcrUrl` - the ModeShape-compatible URL that specifies the `JcrEngine` to be used; may not be null
  Returns:
    the `Repositories` instance specified by the given url if one exists, otherwise `null`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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