org.modeshape.jcr

## Class ModeShapeEngine

- java.lang.Object
- - org.modeshape.jcr.ModeShapeEngine

- All Implemented Interfaces:
    Repositories

      @ThreadSafe
      public class ModeShapeEngine
      extends Object
      implements Repositories

  A container for repositories.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `ModeShapeEngine.State`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ModeShapeEngine()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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,ModeShapeEngine.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.
    `ModeShapeEngine.State` | `getRepositoryState(String repositoryName)` Get the state of the deployed `Repository` instance with the given the name.
    `ModeShapeEngine.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

    - #### ModeShapeEngine

          public ModeShapeEngine()

  - ### Method Detail

    - #### checkRunning

          protected final boolean checkRunning()

    - #### getState

          public ModeShapeEngine.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 ModeShapeEngine.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,ModeShapeEngine.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:

             ModeShapeEngine 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`

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