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

static class

ModeShapeEngine.State

Constructor Summary

ModeShapeEngine()

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