org.wandora.modules.servlet

Class GenericContext

java.lang.Object

org.wandora.modules.AbstractModule

org.wandora.modules.servlet.GenericContext

All Implemented Interfaces:

Module, ActionHandler, ServletModule, ServletModule.RequestListener

Direct Known Subclasses:

AbstractControlledContext, BundleContext, SourceRestrictedContext

public class GenericContext
extends AbstractModule
implements ServletModule, ServletModule.RequestListener, ActionHandler

A base for context modules. Context modules split a ServletModule into several different contexts. The context modules themselves are also ServletModules, they just take some of the root servlet module requests and forward them to actions registered to the specific context module. Actions see the context as any other ServletModule.

Context modules may do something to the request before forwarding it, for example to restrict the use of the other modules registered to it. This could, for example, be user authentication with a username and a password, or checking that the request originates from localhost or something similar. You could also just add more specific logging for each request and the unconditionally pass on the request.

The GenericContext contains some common features, and can serve as a base class for other contexts, although it's not required to extend it. You can also just directly implement ServletModule and appear as a servlet to other modules. Naturally you will also need to implement ServletModule.RequestListener to register your context to the root servlet module. It is also recommended that you implement ActionHandler, which adds some features to the RequestListener and aids in forwarding requests.

GenericContext is not abstract and can be used on its own for some purposes. It can be used to add custom exception handling for actions inside the context, or to group actions by request path or local server directory.

Grouping actions by request path works with the initialisation parameter urlPrefix. This sets a prefix that the request path must use for the request to be passed in this context. The prefix is also removed from the request so that you can nest more urlPrefix restricted contexts inside.

The local context path can be changed with the contextPath initialisation parameter. By default the context path is the server path. Actions may use this as a basis for accessing their files, but are not required to. The contextPath resets this path. You can also use contextDir initialisation parameter to set both urlPrefix and contextPath at the same time. For example, if your server directory has a subdirectory "webapp", then setting contextPath to "webapp" would set that directory as the default path for actions in this context, and would pass the request to them only when the request has the path prefix "webapp".

Another thing that GenericContext does without any extending is provide a hook for exception handling in actions. This is done by including any module that implements ActionExceptionHandler. GenericContext uses it as an optional dependency, so one will be found automatically if you define it in your config. To have different exception handlers for different contexts, use the priority or useService mechanics to specify which one to use with which context. Whenever an ActionException occurs within an action inside this context, it'll be given to the exception handler if one is available. Other exceptions than ActionExceptions won't be caught by the handler. See ActionExceptionHandler for more details.

Overriding classes should override at least doForwardRequest, which checks if the request should be forwarded on. You can implement access restrictions by just overriding this. You may also want to override isHandleAction, it is one of the first checks after receiving a request. Basically it checks if any of the registered actions is going to be interested in the request, if not, the context will drop the request immediately. Naturally you may also override handleRequest to do your own processing and then possibly call the super implementation.

In the initialisation parameters, you may set checkActions to false to disable the initial check of whether any registered actions are interested in the request. The initial check is possibly only for actions implementing ActionHandler, if any of your actions does not implement ActionHandler, you must disable the initial check or they will never receive the requests.

You can set the parameter exceptionOnAuthentication to false to disable throwing of exceptions when user fails to authenticate, or generally just when doForwardRequest returns a value that the request should not be forwarded. The default behaviour is to throw an exception which will then be handled by the previous context, or the root servlet, in some way, most likely as presenting an error of some kind to the user. If this behaviour is disabled, then handleRequest will just simply return false and the previous context will try other possible handlers. Thus you can have behaviour where this context handles requests if the user is logged in, but if they aren't, it's not strictly an error condition.

Author:

olli

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GenericContext.ForwardResult A helper class to contain information about forwarding a request to actions.

Nested classes/interfaces inherited from interface org.wandora.modules.servlet.ServletModule

ServletModule.RequestListener

Field Summary

Fields

Modifier and Type	Field and Description
protected java.lang.String	authenticationErrorMessage
protected boolean	checkActions
protected java.lang.String	contextPath
protected ActionExceptionHandler	exceptionHandler
protected boolean	exceptionOnAuthentication
protected ParallelListenerList<ServletModule.RequestListener>	requestListeners
protected ServletModule	servlet
protected java.lang.String	urlPrefix

Fields inherited from class org.wandora.modules.AbstractModule

autoStart, isInitialized, isRunning, logging, loggingModule, moduleManager

Constructor Summary

Constructors

Constructor and Description
GenericContext()

Method Summary

Modifier and Type	Method and Description
void	addRequestListener(ServletModule.RequestListener listener)
protected GenericContext.ForwardResult	doForwardRequest(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, ModulesServlet.HttpMethod method) Checks if a request should be forwarded to the registered listeners.
java.lang.String	getContextPath() Returns the local path which this servlet should use as a basis for files it needs to access.
java.util.Collection<Module>	getDependencies(ModuleManager manager) Returns all the modules this module depends on.
ActionHandler	getHandlingAction(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, ModulesServlet.HttpMethod method) Gets the Action that will probably handle the given request.
java.lang.String	getServletURL() Returns the base URL for this servlet.
boolean	handleRequest(javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response, ModulesServlet.HttpMethod method, User user) Handles the request, if this is the type of request the listener is interested in.
void	init(ModuleManager manager, java.util.HashMap<java.lang.String,java.lang.Object> settings) Initialises the module.
boolean	isHandleAction(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, ModulesServlet.HttpMethod method) Checks if this action handler will try to handle the given action without handling it yet or causing any side effects.
void	removeRequestListener(ServletModule.RequestListener listener)
void	start(ModuleManager manager) Starts the module.
void	stop(ModuleManager manager) Stops the module.
private javax.servlet.http.HttpServletRequest	wrapRequest(javax.servlet.http.HttpServletRequest req)

Methods inherited from class org.wandora.modules.AbstractModule

isInitialized, isRunning, requireLogging, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.wandora.modules.Module

isInitialized, isRunning

Field Detail

servlet

protected ServletModule servlet

checkActions

protected boolean checkActions

exceptionHandler

protected ActionExceptionHandler exceptionHandler

exceptionOnAuthentication

protected boolean exceptionOnAuthentication

authenticationErrorMessage

protected java.lang.String authenticationErrorMessage

urlPrefix

protected java.lang.String urlPrefix

contextPath

protected java.lang.String contextPath

requestListeners

protected final ParallelListenerList<ServletModule.RequestListener> requestListeners

Constructor Detail

GenericContext

public GenericContext()

Method Detail

getDependencies

public java.util.Collection<Module> getDependencies(ModuleManager manager)
                                             throws ModuleException

Description copied from interface: Module

Returns all the modules this module depends on. This method will be called after init and the dependencies are allowed to depend on the parameters passed to init. The modules that this module depends on must be returned as a collection. In addition, if any required module is not present, a MissingDependencyException should be thrown. Typically you will use the requireModule and optionalModule methods of the manager to make sure that the modules exist and add them to the collection. requireModule will automatically throw the exception too if the module is not found whereas optionalModule does not.

Specified by:

getDependencies in interface Module

Overrides:

getDependencies in class AbstractModule

Parameters:

manager - The module manager handling this module.

Returns:

A collection of modules this module depends on.

Throws:

ModuleException

init

public void init(ModuleManager manager,
                 java.util.HashMap<java.lang.String,java.lang.Object> settings)
          throws ModuleException

Description copied from interface: Module

Initialises the module. After constructor, this is the first method called in the life cycle of a module. It should not perform anything time consuming or anything with notable outside side effects. It should only read the parameters and initialise the module so that it can later be started. Note that a module being initialised doesn't mean that it necessarily will ever be started.

A ModuleException may be thrown if something vital is missing from the parameters or they are not sensible. In some cases you may not want to throw an exception even if vital initialisation information is missing. If, for example, it is possible that the module is initialised in some other way between the init and the start method calls. A ModuleException may also be thrown at the start method if the module is still not initialised.

Specified by:

init in interface Module

Overrides:

init in class AbstractModule

Parameters:

manager - The module manager handling this module. You may keep a reference to it if needed.

Throws:

ModuleException

start

public void start(ModuleManager manager)
           throws ModuleException

Description copied from interface: Module

Starts the module. This will be called after init and getDependencies and signals that the module should now begin to perform whatever it was designed to do. This method call however should not block for long, so any time consuming tasks should be started in their own threads. You will typically get references to the required modules again in start using the findModule method of the manager and then store those references to instance variables for later use. You may throw a ModuleException if the module is not in a state where it can be started or it immediately becomes obvious that it cannot be started with the provided settings.

Specified by:

start in interface Module

Overrides:

start in class AbstractModule

Parameters:

manager - The module manager handling this module.

Throws:

ModuleException

stop

public void stop(ModuleManager manager)

Description copied from interface: Module

Stops the module. Should stop all threads used by the module, free any large data structures and perform other cleanup. It is possible that the module will be started again later with a start method call (and foregoing init and getDependencies calls). The module should be left in a state where this is possible.

Specified by:

stop in interface Module

Overrides:

stop in class AbstractModule

Parameters:

manager - The module manager handling this module.

addRequestListener

public void addRequestListener(ServletModule.RequestListener listener)

Specified by:

addRequestListener in interface ServletModule

removeRequestListener

public void removeRequestListener(ServletModule.RequestListener listener)

Specified by:

removeRequestListener in interface ServletModule

getServletURL

public java.lang.String getServletURL()

Description copied from interface: ServletModule

Returns the base URL for this servlet.

Specified by:

getServletURL in interface ServletModule

Returns:

The base URL for this servlet.

getContextPath

public java.lang.String getContextPath()

Description copied from interface: ServletModule

Returns the local path which this servlet should use as a basis for files it needs to access.

Specified by:

getContextPath in interface ServletModule

Returns:

A local path which should be the basis of local files.

wrapRequest

private javax.servlet.http.HttpServletRequest wrapRequest(javax.servlet.http.HttpServletRequest req)

doForwardRequest

protected GenericContext.ForwardResult doForwardRequest(javax.servlet.http.HttpServletRequest req,
                                                        javax.servlet.http.HttpServletResponse resp,
                                                        ModulesServlet.HttpMethod method)
                                                 throws javax.servlet.ServletException,
                                                        java.io.IOException,
                                                        ActionException

Checks if a request should be forwarded to the registered listeners. The return value is in the form of a ForwardResult object. This combines multiple things about how the request can be handled. See its documentation for more detail.

The default implementation simply returns new ForwardResult(true, false, null), thus forwarding all requests without any additional handling.

Parameters:

req - The HTTP request.

resp - The HTTP response.

method - The HTTP method.

Returns:

A ForwardResult object indicating what to do, or what has been done, with the request.

Throws:

javax.servlet.ServletException

java.io.IOException

ActionException

handleRequest

public boolean handleRequest(javax.servlet.http.HttpServletRequest request,
                             javax.servlet.http.HttpServletResponse response,
                             ModulesServlet.HttpMethod method,
                             User user)
                      throws javax.servlet.ServletException,
                             java.io.IOException,
                             ActionException

Description copied from interface: ServletModule.RequestListener

Handles the request, if this is the type of request the listener is interested in. If the listener does not wish to handle the request, it should return false. False return value indicates that the request should be passed to other listeners, a true return value indicates that this should not happen and a response to the request has been sent. Thus it is possible that you perform some action and still return false and let some other action write the response.

However, keep in mind that some other listener may grab any request before your listener and your listener will then never even see the request. Thus, you will not necessarily be notified of every single request. If this is your goal, you should probably make a separate context that all requests will pass through before they are passed on to other actions, see GenericContext.

Specified by:

handleRequest in interface ServletModule.RequestListener

Parameters:

request - The HTTP request.

response - The HTTP response.

method - The HTTP method of the request.

user - The logged in user if applicable or null.

Returns:

True if a response has been sent and no further listener should try to process the request. False if the request can be forwarded to other listeners for processing.

Throws:

javax.servlet.ServletException

java.io.IOException

ActionException

getHandlingAction

public ActionHandler getHandlingAction(javax.servlet.http.HttpServletRequest req,
                                       javax.servlet.http.HttpServletResponse resp,
                                       ModulesServlet.HttpMethod method)

Gets the Action that will probably handle the given request. Note that this only returns the first action that gets the opportunity to handle the request that claims that it can handle it. The action might later decide not to handle the request in which case the request is passed to the next action that claims it can handle the request. So this method is really only a guess at what action will probably handle the request.

Furthermore, this check depends on actions implementing the ActionHandler interface. Actions in general are not required to do this, although it is recommended that they do. If they don't, this method will just skip over them and never return any such action. However, when the request is actually handled by this context, even actions not implementing ActionHandler will be offered a chance to handle it. Thus it could end up handling the request, even before the action returned by this method.

Parameters:

req - The HTTP request.

resp - The HTTP response.

method - The method of the HTTP request.

Returns:

The action that will first get the opportunity to handle the request and that claims that it will try to handle it.

isHandleAction

public boolean isHandleAction(javax.servlet.http.HttpServletRequest req,
                              javax.servlet.http.HttpServletResponse resp,
                              ModulesServlet.HttpMethod method)

Description copied from interface: ActionHandler

Checks if this action handler will try to handle the given action without handling it yet or causing any side effects. Returning true means that the action handler will try to handle it, not necessarily that the action will succeed. You may also return false from the handleRequest method even if you return true here. The return value should be your best guess as to whether you will handle it without spending too much time checking.

Specified by:

isHandleAction in interface ActionHandler

Parameters:

req - The HTTP request.

resp - The HTTP response.

method - The HTTP method of the request.

Returns: