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 JcrEngine

    java.lang.Object
      org.modeshape.jcr.JcrEngine

All Implemented Interfaces:
  Repositories

    @ThreadSafe
    public class JcrEngine

extends Object
implements Repositories

A container for repositories.

Nested Class Summary
`protected class` | `JcrEngine.GarbageCollectionTask`
`static class` | `JcrEngine.State`

Constructor Summary
`JcrEngine()`

Method Summary
`protected boolean` | `checkRunning()`
`JcrRepository` | `deploy(RepositoryConfiguration repositoryConfiguration)` Deploy a new repository with the given configuration.
`protected JcrRepository` | `deploy(RepositoryConfiguration repositoryConfiguration, String repositoryKey)` Deploy a new repository with the given configuration.
`protected boolean` | `doShutdown()` Do the work of shutting down this engine and its repositories.
`Map<String,JcrEngine.State>` | `getRepositories()` Get an instantaneous snapshot of the JCR repositories and their state.
`JcrRepository` | `getRepository(String repositoryName)` Get the deployed `Repository` instance with the given the name.
`RepositoryConfiguration` | `getRepositoryConfiguration(String repositoryName)` Get the immutable configuration for the repository with the supplied name.
`protected Set<String>` | `getRepositoryKeys()`
`Set<String>` | `getRepositoryNames()` Get the names of the available repositories.
`JcrEngine.State` | `getRepositoryState(String repositoryName)` Get the state of the deployed `Repository` instance with the given the name.
`JcrEngine.State` | `getState()` Get the running state of this engine.
`protected Collection<JcrRepository>` | `repositories()` Returns a copy of the repositories.
`Future<Boolean>` | `shutdown()` Shutdown this engine to stop all repositories, terminate any ongoing background operations (such as sequencing), and reclaim any resources that were acquired by this engine.
`Future<Boolean>` | `shutdown(boolean forceShutdownOfAllRepositories)` Shutdown this engine, optionally stopping all still-running repositories.
`Future<Boolean>` | `shutdownRepository(String repositoryName)` Asynchronously shutdown the deployed `Repository` instance with the given the name, and return a future that will return whether the Repository instance is shutdown.
`void` | `start()` Start this engine to make it available for use.
`Future<JcrRepository>` | `startRepository(String repositoryName)` Asynchronously start the deployed `Repository` instance with the given the name, and return a future that will return the Repository instance.
`Future<Boolean>` | `undeploy(String repositoryName)` Stop and undeploy the named `Repository`.
`Future<JcrRepository>` | `update(String repositoryName, Changes changes)` Update the configuration of a deployed repository by applying the set of changes to that repository's configuration.

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

Constructor Detail

### JcrEngine

    public JcrEngine()

Method Detail

### checkRunning

    protected final boolean checkRunning()

### getState

    public JcrEngine.State getState()

  Get the running state of this engine.

  Returns:
    the current state; never null

### start

    public void start()

  Start this engine to make it available for use. This method does nothing if the engine is already running.

  See Also:
    `shutdown()`

### shutdown

    public Future<Boolean> shutdown()

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

  This is equivalent to calling `shutdown(true)`

  Returns:
    a future that allows the caller to block until the engine is shutdown; any error during shutdown will be thrown when `getting` the result 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.
  See Also:
    `start()`

### shutdown

    public Future<Boolean> shutdown(boolean forceShutdownOfAllRepositories)

  Shutdown this engine, optionally stopping all still-running repositories.

  Parameters:
    `forceShutdownOfAllRepositories` - true if the engine should be shutdown even if there are currently-running repositories, or false if the engine should not be shutdown if at least one repository is still running.
  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.
  See Also:
    `start()`

### doShutdown

    protected boolean doShutdown()

  Do the work of shutting down this engine and its repositories.

  Returns:
    true if the engine was shutdown (or was not running), and false if the engine is still running and could not be shutdown

### getRepository

    public final JcrRepository getRepository(String repositoryName)
                                      throws NoSuchRepositoryException

  Get the deployed `Repository` instance with the given the name.

  Specified by:
    `getRepository` in interface `Repositories`
  Parameters:
    `repositoryName` - the name of the deployed repository
  Returns:
    the named repository instance
  Throws:
    `IllegalArgumentException` - if the repository name is null, blank or invalid
    `NoSuchRepositoryException` - if there is no repository with the specified name
    `IllegalStateException` - if this engine is not `running`
  See Also:
    `deploy(RepositoryConfiguration)`, `undeploy(String)`

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

### getRepositoryKeys

    protected Set<String> getRepositoryKeys()

### getRepositoryState

    public final JcrEngine.State getRepositoryState(String repositoryName)
                                             throws NoSuchRepositoryException

  Get the state of the deployed `Repository` instance with the given the name.

  Parameters:
    `repositoryName` - the name of the deployed repository
  Returns:
    the state of the repository instance; never null
  Throws:
    `IllegalArgumentException` - if the repository name is null, blank or invalid
    `NoSuchRepositoryException` - if there is no repository with the specified name
    `IllegalStateException` - if this engine is not `running`
  See Also:
    `deploy(RepositoryConfiguration)`, `undeploy(String)`

### getRepositoryConfiguration

    public final RepositoryConfiguration getRepositoryConfiguration(String repositoryName)
                                                             throws NoSuchRepositoryException

  Get the immutable configuration for the repository with the supplied name.

  Parameters:
    `repositoryName` - the name of the deployed repository
  Returns:
    the repository configuration; never null
  Throws:
    `IllegalArgumentException` - if the repository name is null, blank or invalid
    `NoSuchRepositoryException` - if there is no repository with the specified name
    `IllegalStateException` - if this engine is not `running`

### startRepository

    public final Future<JcrRepository> startRepository(String repositoryName)
                                                throws NoSuchRepositoryException

  Asynchronously start the deployed `Repository` instance with the given the name, and return a future that will return the Repository instance. If the Repository is already running, this method returns a future that returns immediately.

  Note that the caller does not have to wait for the startup process to complete. However, to do so the caller merely calls `get()` or `get(long,TimeUnit)` on the future to return the repository instance. Note that any exceptions thrown during the startup process will be wrapped in an `ExecutionException` thrown by the Future's `get` methods.

  Parameters:
    `repositoryName` - the name of the deployed repository
  Returns:
    the state of the repository instance; never null
  Throws:
    `IllegalArgumentException` - if the repository name is null, blank or invalid
    `NoSuchRepositoryException` - if there is no repository with the specified name
    `IllegalStateException` - if this engine is not `running`
  See Also:
    `deploy(RepositoryConfiguration)`, `undeploy(String)`

### shutdownRepository

    public final Future<Boolean> shutdownRepository(String repositoryName)
                                             throws NoSuchRepositoryException

  Asynchronously shutdown the deployed `Repository` instance with the given the name, and return a future that will return whether the Repository instance is shutdown. If the Repository is not running, the resulting future will return immediately.

  Note that the caller does not have to wait for the shutdown to completed. However, to do so the caller merely calls `get()` or `get(long,TimeUnit)` on the future to return a boolean flag specifying whether the Repository instance is shutdown (not running). Note that any exceptions thrown during the shutdown will be wrapped in an `ExecutionException` thrown by the Future's `get` methods.

  Parameters:
    `repositoryName` - the name of the deployed repository
  Returns:
    a future wrapping the asynchronous shutdown process; never null, and `Future.get()` will return whether the
  Throws:
    `IllegalArgumentException` - if the repository name is null, blank or invalid
    `NoSuchRepositoryException` - if there is no repository with the specified name
    `IllegalStateException` - if this engine is not `running`
  See Also:
    `deploy(RepositoryConfiguration)`, `undeploy(String)`

### getRepositories

    public Map<String,JcrEngine.State> getRepositories()

  Get an instantaneous snapshot of the JCR repositories and their state. Note that the results are accurate only when this methods returns.

  Returns:
    the immutable map of repository states keyed by repository names; never null

### repositories

    protected Collection<JcrRepository> repositories()

  Returns a copy of the repositories. Note that when returned, not all repositories may be active.

  Returns:
    a copy of the repositories; never null

### deploy

    public JcrRepository deploy(RepositoryConfiguration repositoryConfiguration)
                         throws ConfigurationException,
                                RepositoryException

  Deploy a new repository with the given configuration. This method will fail if this engine already contains a repository with the specified name.

  Parameters:
    `repositoryConfiguration` - the configuration for the repository
  Returns:
    the deployed repository instance, which must be `started` before it can be used; never null
  Throws:
    `ConfigurationException` - if the configuration is not valid
    `RepositoryException` - if there is already a deployed repository with the specified name, or if there is a problem deploying the repository
    `IllegalArgumentException` - if the configuration is null
  See Also:
    `deploy(RepositoryConfiguration)`, `update(String, Changes)`, `undeploy(String)`

### deploy

    protected JcrRepository deploy(RepositoryConfiguration repositoryConfiguration,
                                   String repositoryKey)
                            throws ConfigurationException,
                                   RepositoryException

  Deploy a new repository with the given configuration. This method will fail if this engine already contains a repository with the specified name.

  Parameters:
    `repositoryConfiguration` - the configuration for the repository
    `repositoryKey` - the key by which this repository is known to this engine; may be null if the `repository's name` should be used
  Returns:
    the deployed repository instance, which must be `started` before it can be used; never null
  Throws:
    `ConfigurationException` - if the configuration is not valid
    `RepositoryException` - if there is already a deployed repository with the specified name, or if there is a problem deploying the repository
    `IllegalArgumentException` - if the configuration is null
  See Also:
    `deploy(RepositoryConfiguration)`, `update(String, Changes)`, `undeploy(String)`

### update

    public Future<JcrRepository> update(String repositoryName,
                                        Changes changes)
                                 throws ConfigurationException,
                                        NoSuchRepositoryException,
                                        RepositoryException

  Update the configuration of a deployed repository by applying the set of changes to that repository's configuration. The changes can be built by obtaining the configuration for the deployed instance, obtaining an editor (which actually contains a copy of the configuration) and using it to make changes, and then getting the changes from the editor. The benefit of this approach is that the changes can be made in an isolated copy of the configuration and all of the changes applied en masse.

  The basic outline for modifying a repository's configuration is as follows:

  1. Get the current configuration for the repository that is to be changed
  2. Get an editor from that configuration
  3. Use the editor to capture and validate the changes you want to make
  4. Update the repository's configuration with the changes from the editor
  Here's some code that shows how this is done:

         JcrEngine engine = ...
         Repository deployed = engine.getRepository("repo");
         RepositoryConfiguration deployedConfig = deployed.getConfiguration();

         // Create an editor, which is actually manipulating a copy of the configuration document ...
         Editor editor = deployedConfig.edit();

         // Modify the copy of the configuration (we'll do something trivial here) ...
         editor.setNumber(FieldName.LARGE_VALUE_SIZE_IN_BYTES,8096);

         // Get our changes and validate them ...
         Changes changes = editor.getChanges();
         Results validationResults = deployedConfig.validate(changes);
         if ( validationResults.hasErrors() ) {
             // you've done something wrong with your editor
         } else {
             // Update the deployed repository's configuration with these changes ...
             Future<Boolean> future = engine.update("repo",changes);

             // Optionally block while the repository instance is changed to
             // reflect the new configuration ...
             JcrRepository updated = future.get();
         }

  Note that this method blocks while the changes to the configuration are validated and applied, but before the repository has changed to reflect the new configuration, which is done asynchronously. The resulting future represents that asynchronous process, and the future can be used to block until that updating is completed.

  Parameters:
    `repositoryName` - the name of the repository
    `changes` - the changes that should be applied to the repository's configuration
  Returns:
    a future that allows the caller to block until the repository has completed all of its changes.
  Throws:
    `ConfigurationException` - if the configuration is not valid with the supplied changes
    `NoSuchRepositoryException` - if there is no repository with the specified name
    `RepositoryException` - if there is a problem updating the repository
    `IllegalArgumentException` - if any of the parameters are null or invalid
  See Also:
    `deploy(RepositoryConfiguration)`, `undeploy(String)`

### undeploy

    public Future<Boolean> undeploy(String repositoryName)
                             throws NoSuchRepositoryException

  Stop and undeploy the named `Repository`.

  Parameters:
    `repositoryName` - the name of the deployed repository
  Returns:
    a future that allows the caller to block until the repository is shutdown; if the repository could not shutdown, `getting` the repository from the future will throw the exception wrapped in a `ExecutionException`
  Throws:
    `IllegalArgumentException` - if the repository name is null, blank or invalid
    `NoSuchRepositoryException` - if there is no repository with the specified name
    `IllegalStateException` - if this engine was not `started`

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.