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

## 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
`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
`Future<Boolean>` | `shutdown()` 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.
`boolean` | `shutdown(long timeout, TimeUnit unit)` 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.

Methods inherited from interface javax.jcr.RepositoryFactory
`getRepository`

Methods inherited from interface org.modeshape.jcr.api.Repositories
`getRepository, getRepositoryNames`

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

    Future<Boolean> shutdown()

  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

    boolean shutdown(long timeout,
                     TimeUnit unit)
                     throws InterruptedException

  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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| ModeShape Distribution 3.0.0.Alpha5
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.