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
Class JcrRepositoryFactory

    java.lang.Object
      org.modeshape.jcr.JcrRepositoryFactory

All Implemented Interfaces:
  RepositoryFactory, Repositories

    @ThreadSafe
    public class JcrRepositoryFactory

extends Object
implements RepositoryFactory

Service provider for the JCR2 `RepositoryFactory` interface. This class provides a single public method, `getRepository(Map)`, that allows for a runtime link to a ModeShape JCR repository.

The canonical way to get a reference to this class is to use the `ServiceLoader`:

     String configUrl = ... ; // URL that points to your configuration file
     Map parameters = Collections.singletonMap(JcrRepositoryFactory.URL, configUrl);
     Repository repository;

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

It is also possible to instantiate this class directly.

     RepositoryFactory repoFactory = new JcrRepositoryFactory();
     String url = ... ; // URL that points to your configuration file
     Map params = Collections.singletonMap(JcrRepositoryFactory.URL, url);

     Repository repository = repoFactory.getRepository(params);]]>

Several URL formats are supported:

- JNDI location of repository - The URL contains the location in JNDI of an existing `javax.jcr.Repository` instance. For example, "`jndi:jcr/local/my_repository`" is a URL that identifies the JCR repository located in JNDI at the name "jcr/local/my_repository". Note that the use of such URLs requires that the repository already be registered in JNDI at that location.
- JNDI location of engine and repository name - The URL contains the location in JNDI of an existing ModeShape `engine` instance and the name of the `javax.jcr.Repository` repository as a URL query parameter. For example, "`jndi:jcr/local?repositoryName=my_repository`" identifies a ModeShape engine registered in JNDI at "jcr/local", and looks in that engine for a JCR repository named "`my_repository`".
- Location of a repository configuration - The URL contains a location that is resolvable to a configuration file for the repository. If the configuration file has not already been loaded by the factory, then the configuration file is read and used to deploy a new repository; subsequent uses of the same URL will return the previously deployed repository instance. Several URL schemes are supported, including `classpath:`, "`file:`", `http:` and any other URL scheme that can be `resolved and opened`. For example, " `file://path/to/myRepoConfig.json`" identifies the file on the file system at the absolute path " `/path/to/myRepoConfig.json`"; "`classpath://path/to/myRepoConfig.json`" identifies the file at " `/path/to/myRepoConfig.json`" on the classpath, and "`http://www.example.com/path/to/myRepoConfig.json` " identifies the file "`myRepoConfig.json`" at the given URL.

See Also:
  `getRepository(Map)`, `RepositoryFactory.getRepository(Map)`

Field Summary
`static String` | `REPOSITORY_NAME_PARAM` The name of the URL parameter that specifies the repository name.
`static String` | `URL` Deprecated. use `RepositoryFactory.URL` instead

Fields inherited from interface org.modeshape.jcr.api.RepositoryFactory
`REPOSITORY_NAME`

Constructor Summary
`JcrRepositoryFactory()`

Method Summary
`Repository` | `getRepository(Map parameters)` Returns a reference to the appropriate repository for the given parameter map, if one exists.
`Repository` | `getRepository(String repositoryName)` Return the JCR Repository with the supplied name.
`Repository` | `getRepository(String jcrUrl, String repositoryName)` Returns the repository with the given name from the `Repositories` referenced by `jcrUrl` if the engine and the named repository exist, null otherwise.
`protected Repository` | `getRepository(URL url, String repositoryName, Map<String,Object> parameters)`
`protected String` | `getRepositoryNameFrom(URL url, Map<String,Object> parameters)`
`Set<String>` | `getRepositoryNames()` Get the names of the available repositories.
`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.
`static Future<Boolean>` | `shutdownAll()` Shutdown this engine to stop all repositories created by calls to `getRepository(Map)`, terminate any ongoing background operations (such as sequencing), and reclaim any resources that were acquired by the repositories.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### URL

    @Deprecated
    public static final String URL

  Deprecated. use `RepositoryFactory.URL` instead
  The name of the key for the ModeShape JCR URL in the parameter map

  See Also:
    Constant Field Values

### REPOSITORY_NAME_PARAM

    public static final String REPOSITORY_NAME_PARAM

  The name of the URL parameter that specifies the repository name.

  See Also:
    Constant Field Values

Constructor Detail

### JcrRepositoryFactory

    public JcrRepositoryFactory()

Method Detail

### shutdownAll

    public static Future<Boolean> shutdownAll()

  Shutdown this engine to stop all repositories created by calls to `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.

  Calling this static method is identical to calling the `shutdown()` method on any JcrRepositoryFactory instance, and is provided for convenience.

  Invoking this method does not preclude creating new `Repository` instances with future calls to `getRepository(Map)`. Any caller using this method as part of an application shutdown process should take care to cease invocations of `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.

### getRepository

    public Repository getRepository(Map parameters)

  Returns a reference to the appropriate repository for the given parameter map, if one exists. Although the `parameters` map can have any number of entries, this method only considers the entry with the key JcrRepositoryFactory#URL.

  The value of this key is treated as a URL with the format `PROTOCOL://PATH[?repositoryName=REPOSITORY_NAME]` where PROTOCOL is "jndi" or "file", PATH is the JNDI name of the JcrEngine or the path to the configuration file, and REPOSITORY_NAME is the name of the repository to return if there is more than one JCR repository in the given JcrEngine or configuration file.

  Specified by:
    `getRepository` in interface `RepositoryFactory`
  Parameters:
    `parameters` - a map of parameters to use to look up the repository; may be null
  Returns:
    the repository specified by the value of the entry with key `URL`, or null if any of the following are true:
    - the parameters map is empty; or,
    - there is no parameter with the `URL`; or,
    - the value for the `URL` key is null or cannot be parsed into a ModeShape JCR URL; or,
    - the ModeShape JCR URL is parseable but does not point to a JcrEngine (in the JNDI tree) or a configuration file (in the classpath or file system); or,
    - or there is an error starting up the JcrEngine with the given configuration information.
  See Also:
    `RepositoryFactory.getRepository(Map)`

### getRepository

    protected Repository getRepository(URL url,
                                       String repositoryName,
                                       Map<String,Object> parameters)

### getRepositoryNameFrom

    protected String getRepositoryNameFrom(URL url,
                                           Map<String,Object> parameters)

### shutdown

    public Future<Boolean> shutdown()

  Description copied from interface: `RepositoryFactory`
  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

    public boolean shutdown(long timeout,
                            TimeUnit unit)
                     throws InterruptedException

  Description copied from interface: `RepositoryFactory`
  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

### getRepository

    public Repository getRepository(String jcrUrl,
                                    String repositoryName)
                             throws RepositoryException

  Returns the repository with the given name from the `Repositories` referenced by `jcrUrl` if the engine and the named repository exist, null otherwise.

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

  If the `repositoryName` parameter is null, the repository name specified in the `jcrUrl` parameter will be used instead. If no repository name is specified in the `jcrUrl` parameter and the `JcrEngine` has exactly one repository, that repository will be used. Otherwise, this method will return `null`.

  Parameters:
    `jcrUrl` - the ModeShape-compatible URL that specifies the `Repositories` to be used; may not be null
    `repositoryName` - the name of the repository to return; may be null
  Returns:
    the `Repository` with the given name from the `Repositories` referenced by `jcrUrl` if the engine exists and can be started (or is already started), and the named repository exists or `null` is provided as the `repositoryName` and the given engine has exactly one repository or the `jcrUrl` specifies a repository. If any of these conditions do not hold, `null` is returned.
  Throws:
    `RepositoryException` - if the named repository exists but cannot be accessed
  See Also:
    `JcrEngine.getRepository(String)`

### getRepository

    public Repository getRepository(String repositoryName)
                             throws RepositoryException

  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

### getRepositoryNames

    public Set<String> getRepositoryNames()

  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

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.