The JBoss DNA repository service is the component that manages the repositories and connections to them. The service reads its configuration from a RepositorySource instance (i.e., the "configuration repository") and automatically sets up the repositories given the RepositorySource instances found in the configuration repository.

To set up the repository service, we need to first set up a few other objects:

With these components in place, we can then instantiate the RepositoryService and start it (using its ServiceAdministrator). During startup, the service reads the configuration repository and loads any defined RepositorySource instances into the repository library, using the class loader factory (available in the ExecutionContext) to obtain.

Here's sample code that shows how to set up and start the repository service. You can see something similar in the example application in the startRepositories() method of the org.jboss.example.dna.repository.RepositoryClient class.

  // Create the execution context that we'll use for the services. If we'd want to use JAAS, we'd 

  // create the context by supplying LoginContext, AccessControlContext, or even Subject with 

  // CallbackHandlers. But this example doesn't use JAAS in this example.

  ExecutionContext context = new ExecutionContext();


  // Create the library for the RepositorySource instances ...

  RepositoryLibrary sources = new RepositoryLibrary(context);


  // Load into the source manager the repository source for the configuration repository ...

  InMemoryRepositorySource configSource = new InMemoryRepositorySource();

  configSource.setName("Configuration");

  sources.addSource(configSource);


  // Now instantiate the Repository Service ...

  RepositoryService service = new RepositoryService(sources, configSource.getName(), context);

  service.getAdministrator().start();

 

After startup completes, the repositories are ready to be used. The client application obtains the list of repositories and presents them to the user. When the user selects one, the client application starts navigating that repository starting at its root node (e.g., the "/" path). As you type a command to list the contents of the current node or to "change directories" to a different node, the client application obtains the information for the node using a simple procedure:

    JcrRepository jcrRepository = new JcrRepository(context, sources);

    Session session = jcrRepository.login(sourceName);

 

  CallbackHandler callbackHandler = // as needed by your app, according to JAAS

  final LoginContext loginContext = new LoginContext("MyAppContextName",callbackHandler);

  Credentials credentials = new Credentials() {

            public LoginContext getLoginContext() { return loginContext; }

  };

  JcrRepository jcrRepository = new JcrRepository(context, sources);

  Session session = jcrRepository.login(credentials, sourceName);

 

  if (session != null) session.logout();

 

In the first part of this chapter, we saw how to instantiate, configure, and start the RepositoryService. We then saw how to use JCR to access the repository service by creating JCR Sessions, and how to log out of those sessions when no longer needed.

In this short section we'll see how to shut down the RepositoryService and RepositoryLibrary when you're finished with all of the repositories. It's a simple but important step, since this closes all outstanding connections that may be sitting unused in the library's connection pools.

Shutting down these components is very straightforward: get the ServiceAdministrator on each, and call shutdown().

  // Shut down the repository service ...

  repositoryService.getAdministrator().shutdown();


  // Shut down the manager of the RepositorySource instances, waiting until all connections are closed

  sources.getAdministrator().shutdown();

  sources.getAdministrator().awaitTermination(1, TimeUnit.SECONDS);

 

The shutdown() method attempts to close all open and unused resources (such as open and unused connections in the pool). No more connections can be created, and any connections that are currently in use are not closed but allowed to be used and closed normally. When the last connection is used, the service then transitions to a terminated state, which you can wait for using the awaitTermination(int,TimeUnit) method.

If you want to shutdown the services immediately, then you could call shutdownNow(), which blocks while it attempts to immediately close all connections - even those currently in use. So, while you generally want to use shutdown(), it is good to be aware that this shutdownNow() method does exist.

Recall that the example repository application consists of a client application that sets up a repository service and the repositories defined in a configuration repository, allowing the user to pick a repository and interactively navigate the selected repository. Several repositories are set up, including several in-memory repositories and one federated repository that dynamically federates the content from the other repositories.

The example is comprised of 2 classes and 1 interface, located in the src/main/java directory:

  org/jboss/example/dna/repositories/ConsoleInput.java
                                    /RepositoryClient.java
                                    /UserInterface.java
  

RepositoryClient is the class that contains the main application. It uses an instance of the UserInterface interface to methods that will be called at runtime to obtain information about the files that are imported into the in-memory repositories and the JAAS CallbackHandler implementation that will be used by JAAS to prompt the user for authentication information. Finally, the ConsoleInput is an implementation of this that creates a text user interface, allowing the user to operate the client from the command-line. We can easily create a graphical implementation of UserInterface at a later date, or we can also create a mock implementation for testing purposes that simulates a user entering data. This allows us to check the behavior of the client automatically using conventional JUnit test cases, as demonstrated by the code in the src/test/java directory:

  org/jboss/example/dna/sequencers/RepositoryClientTest.java
                                  /RepositoryClientUsingJcrTest.java
  

The code we presented earlier in this chapter represent the bulk of the JBoss DNA and JCR-specific code used in the RepositoryClient, so we won't cover it in any more detail here. Please refer to the sample client code if you want to see more.

In this chapter we covered the different JBoss DNA components used for accessing repositories through JCR, including repositories that federate their content from the content of other repositories. Specifically, we described how the RepositoryService and JcrRepository can be configured and used.