org.apache.jackrabbit.j2ee
Class RepositoryStartupServlet

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          org.apache.jackrabbit.servlet.AbstractRepositoryServlet
              org.apache.jackrabbit.j2ee.RepositoryStartupServlet

All Implemented Interfaces:

Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

public class RepositoryStartupServlet
extends AbstractRepositoryServlet

The RepositoryStartupServlet starts a jackrabbit repository and registers it to the JNDI environment and optional to the RMI registry.

Registration with RMI

Upon successfull creation of the repository in the init() method, the repository is registered with an RMI registry if the web application is so configured. To register with RMI, the following web application init-params are considered: rmi-port designating the port on which the RMI registry is listening, rmi-host designating the interface on the local host on which the RMI registry is active, repository-name designating the name to which the repository is to be bound in the registry, and rmi-uri designating an RMI URI complete with host, optional port and name to which the object is bound.

If the rmi-uri parameter is configured with a non-empty value, the rmi-port and rmi-host parameters are ignored. The repository-name parameter is only considered if a non-empty rmi-uri parameter is configured if the latter does not contain a name to which to bind the repository.

This is the algorithm used to find out the host, port and name for RMI registration:

1. If neither a rmi-uri nor a rmi-host nor a rmi-port parameter is configured, the repository is not registered with any RMI registry.
2. If a non-empty rmi-uri parameter is configured extract the host name (or IP address), port number and name to bind to from the URI. If the URI is not valid, host defaults to 0.0.0.0 meaning all interfaces on the local host, port defaults to the RMI default port (1099) and the name defaults to the value of the repository-name parameter.
3. If a non-empty rmi-uri is not configured, the host is taken from the rmi-host parameter, the port from the rmi-port parameter and the name to bind the repository to from the repository-name parameter. If the rmi-host parameter is empty or not configured, the host defaults to 0.0.0.0 meaning all interfaces on the local host. If the rmi-port parameter is empty, not configured, zero or a negative value, the default port for the RMI registry (1099) is used.

After finding the host and port of the registry, the RMI registry itself is acquired. It is assumed, that host and port primarily designate an RMI registry, which should be active on the local host but has not been started yet. In this case, the LocateRegistry.createRegistry method is called to create a registry on the local host listening on the host and port configured. If creation fails, the LocateRegistry.getRegistry method is called to get a remote instance of the registry. Note, that getRegistry does not create an actual registry on the given host/port nor does it check, whether an RMI registry is active.

When the registry has been retrieved, either by creation or by just creating a remote instance, the repository is bound to the configured name in the registry.

Possible causes for registration failures include:

• The web application is not configured to register with an RMI registry at all.
• The registry is expected to be running on a remote host but does not.
• The registry is expected to be running on the local host but cannot be accessed. Reasons include another application which does not act as an RMI registry is running on the configured port and thus blocks creation of a new RMI registry.
• An object may already be bound to the same name as is configured to be used for the repository.

Note: if a bootstrap-config init parameter is specified the servlet tries to read the respective resource, either as context resource or as file. The properties specified in this file override the init params specified in the web.xml.

Setup Wizard Functionality
When using the first time, the configuraition can miss the relevant repository parameters in the web.xml. if so, it must contain a bootstrap-config parameter that referrs to a propertiy file. This file must exsit for proper working. If not, the repository is not started.
If the servlet is not configured correctly and accessed via http, it will provide a simple wizard for the first time configuration. It propmpts for a new (or existing) repository home and will copy the templates of the repository.xml and bootstrap.properties to the respective location.

See Also:

Serialized Form

Nested Class Summary

protected static class	RepositoryStartupServlet.RemoteFactoryDelegater optional class for RMI, will only be used, if RMI server is present
protected static class	RepositoryStartupServlet.RMIRemoteFactoryDelegater optional class for RMI, will only be used, if RMI server is present

Field Summary

static String

INIT_PARAM_BOOTSTRAP_CONFIG initial param name for the bootstrap config location

Constructor Summary

RepositoryStartupServlet()

Method Summary

protected Repository	createRepository(InputSource is, File homedir) Creates the repository instance for the given config and homedir.
void	destroy() destroy the servlet
protected void	doGet(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp) Outputs the repository descriptors either as a collection of properties (see Properties.store(java.io.OutputStream, String) or individually addressable text/plain resources based on the request URI.
protected void	doPost(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
BootstrapConfig	getBootstrapConfig() Returns the config that was used to bootstrap this servlet.
static RepositoryStartupServlet	getInstance(javax.servlet.ServletContext context) Returns an instance of this servlet.
protected String	getRemoteFactoryDelegaterClass() Return the fully qualified name of the class providing the remote repository.
Repository	getRepository() Returns the started repository or null if not started yet.
RepositoryFactory	getRepositoryFactory() Returns a repository factory that returns the repository if available or throws an exception if not.
protected RMIServerSocketFactory	getRMIServerSocketFactory(InetAddress hostAddress) Returns an RMIServerSocketFactory used to create the server socket for a locally created RMI registry.
void	init() Initializes the servlet.
void	restart() Restarts the repository.
void	shutdown() Does a shutdown of the repository and deregisters it from the RMI registry and unbinds if from the JNDI context if so configured.
void	startup() Configures and starts the repository.

Methods inherited from class org.apache.jackrabbit.servlet.AbstractRepositoryServlet

getAttributeName, getInitParameter

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doHead, doOptions, doPut, doTrace, getLastModified, service, service

Methods inherited from class javax.servlet.GenericServlet

getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INIT_PARAM_BOOTSTRAP_CONFIG

public static final String INIT_PARAM_BOOTSTRAP_CONFIG

initial param name for the bootstrap config location

See Also:

Constant Field Values

Constructor Detail

RepositoryStartupServlet

public RepositoryStartupServlet()

Method Detail

init

public void init()
          throws javax.servlet.ServletException

Initializes the servlet.
Please note that only one repository startup servlet may exist per webapp. it registers itself as context attribute and acts as singleton.

Overrides:

init in class AbstractRepositoryServlet

Throws:

javax.servlet.ServletException - if a same servlet is already registered or of another initialization error occurs.

getInstance

public static RepositoryStartupServlet getInstance(javax.servlet.ServletContext context)

Returns an instance of this servlet. Please note, that only 1 repository startup servlet can exist per webapp.

Parameters:

context - the servlet context

Returns:

this servlet

startup

public void startup()
             throws javax.servlet.ServletException

Configures and starts the repository. It registers it then to the RMI registry and bind is to the JNDI context if so configured.

Throws:

javax.servlet.ServletException - if an error occurs.

shutdown

public void shutdown()

Does a shutdown of the repository and deregisters it from the RMI registry and unbinds if from the JNDI context if so configured.

restart

public void restart()
             throws javax.servlet.ServletException

Restarts the repository.

Throws:

javax.servlet.ServletException - if an error occurs.

See Also:

shutdown(), startup()

destroy

public void destroy()

destroy the servlet

Specified by:

destroy in interface javax.servlet.Servlet

Overrides:

destroy in class AbstractRepositoryServlet

getRepository

public Repository getRepository()

Returns the started repository or null if not started yet.

Specified by:

getRepository in class AbstractRepositoryServlet

Returns:

the JCR repository

getRepositoryFactory

public RepositoryFactory getRepositoryFactory()

Returns a repository factory that returns the repository if available or throws an exception if not.

Returns:

repository factory

createRepository

protected Repository createRepository(InputSource is,
                                      File homedir)
                               throws RepositoryException

Creates the repository instance for the given config and homedir. Subclasses may override this method of providing own implementations of a Repository.

Parameters:

is - input source of the repository config

homedir - the repository home directory

Returns:

a new jcr repository.

Throws:

RepositoryException - if an error during creation occurs.

getBootstrapConfig

public BootstrapConfig getBootstrapConfig()

Returns the config that was used to bootstrap this servlet.

Returns:

the bootstrap config or null.

getRemoteFactoryDelegaterClass

protected String getRemoteFactoryDelegaterClass()

Return the fully qualified name of the class providing the remote repository. The class whose name is returned must implement the RepositoryStartupServlet.RemoteFactoryDelegater interface.

Subclasses may override this method for providing a name of a own implementation.

Returns:

getClass().getName() + "$RMIRemoteFactoryDelegater"

getRMIServerSocketFactory

protected RMIServerSocketFactory getRMIServerSocketFactory(InetAddress hostAddress)

Returns an RMIServerSocketFactory used to create the server socket for a locally created RMI registry.

This implementation returns a new instance of a simple RMIServerSocketFactory which just creates instances of the java.net.ServerSocket class bound to the given hostAddress. Implementations may overwrite this method to provide factory instances, which provide more elaborate server socket creation, such as SSL server sockets.

Parameters:

hostAddress - The InetAddress instance representing the the interface on the local host to which the server sockets are bound.

Returns:

A new instance of a simple RMIServerSocketFactory creating java.net.ServerSocket instances bound to the rmiHost.

doGet

protected void doGet(javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse resp)
              throws javax.servlet.ServletException,
                     IOException

Outputs the repository descriptors either as a collection of properties (see Properties.store(java.io.OutputStream, String) or individually addressable text/plain resources based on the request URI.

A typical mapping for a repository servlet would be:

 <servlet-mapping>
   <servlet-name>Repository</servlet-name>
   <url-pattern>/repository/*</url-pattern>
 </servlet-mapping>
 

This mapping would allow clients to retrieve all repository descriptors from http://server/context/repository/ and to address individual descriptors by key with URIs like http://server/context/repository/key. For example, the name of the repository vendor could be retrieved from http://server/context/repository/jcr.repository.vendor. Likewise, a 404 (not found) response from http://server/context/repository/level.2.supported would indicate that the repository does not support Level 2 features.

Note that mapping a repository servlet to the URL space is optional, as the main purpose of the servlet is to make a repository available in the servlet context, not to expose repository information to web clients.

Overrides:

doGet in class AbstractRepositoryServlet

Parameters:

req - HTTP request

resp - HTTP response

Throws:

javax.servlet.ServletException - on servlet errors

IOException - on IO errors

doPost

protected void doPost(javax.servlet.http.HttpServletRequest req,
                      javax.servlet.http.HttpServletResponse resp)
               throws javax.servlet.ServletException,
                      IOException

Overrides:

doPost in class javax.servlet.http.HttpServlet

Throws:

javax.servlet.ServletException

IOException