org.barracudamvc.core.event
Class ApplicationGateway

java.lang.Object
  extended by javax.servlet.GenericServlet
      extended by javax.servlet.http.HttpServlet
          extended by org.barracudamvc.core.event.ApplicationGateway
All Implemented Interfaces:
Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig, EventGateway
Direct Known Subclasses:
SampleApplicationGateway

public class ApplicationGateway
extends javax.servlet.http.HttpServlet
implements EventGateway

The application gateway is responsible for a number of things.

  1. It acts as a gateway servlet for all event handlers in this application.
  2. It defines and instantiates a number of entities needed to dispatch events (EventBroker, EventPool, DispatcherFactory, etc)
  3. It defines which event extension we are using
  4. It registers all EventGateways, and any local Event interests
  5. It performs the initial mapping of HTTPRequests to Events for this particular domain

Consequently, if you want to use the Barracuda event model, this is the class that really kicks it all off. You must either extend this class OR use the DefaultApplicationAssembler in order to specify that this servlet handles all event requests for an application. This will allow the system to convert requests to events and dispatch them through the EventBroker to any listeners within EventGateways that have registered interest with the broker.

This class should be the first servlet loaded in your web.xml file.

For an example of how to do this, look at org.barracudamvc.examples.ex1.SampleApplicationGateway

You might also want to look at the UML Class diagram of the Event model classes.

Since:
1.0
Version:
%I%, %G%
Author:
Christian Cryder , Diez Roggisch , Jacob Kjome
See Also:
Serialized Form

Field Summary
static boolean ENABLE_LR_EVENTS
           
protected  EventGateway eventGateway
           
static String EXTERNAL_CONTEXT_OBJ_NAME
           
protected  List gateways
           
static String HTTP_SERVLET_REQUEST
           
static String HTTP_SERVLET_RESPONSE
           
static String LR_ID
           
static String LR_OR
           
static String LR_OVERRIDE_KEY
           
static String LR_SOR
           
static RequestWrapper REQUEST_WRAPPER
           
static boolean RESPOND_WITH_404
           
static ResponseWrapper RESPONSE_WRAPPER
           
static String TARGET_EVENT_NAME
           
static String THREAD_POOL
           
static boolean USE_EVENT_POOLING
           
protected  boolean virgin
           
 
Constructor Summary
ApplicationGateway()
          Public noargs constructor
 
Method Summary
 void add(EventGateway eg)
          Add an event gateway to this one
 void deregister(EventBroker eb)
          Ask all interested parties to de-register with the EventBroker
 void deregisterLocalEventInterests(EventBroker eb)
          Deregister any local interests in the EventBroker
 void destroy()
          Here's where we destroy the servlet.
 void destroyLocal()
          Perform any local cleanup (this is where you should remove any known EventGateways)
protected  void doDelete(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          By default the DELETE request is mapped to the handleDefault method
protected  void doGet(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          By default the GET request is mapped to the handleDefault method
protected  void doOptions(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          By default the OPTIONS request is mapped to the handleDefault method
protected  void doPost(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          By default the POST request is mapped to the handleDefault method
protected  void doPut(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          By default the PUT request is mapped to the handleDefault method
protected  void doTrace(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          By default the TRACE request is mapped to the handleDefault method
 List getChildren()
          Get a list of child gateways.
 DispatcherFactory getDispatcherFactory()
          Provide an instance of the specific EventDispatcher we want to use.
 EventBroker getEventBroker()
          Provide a reference to the event broker.
 String getEventExtension()
          Indicate which event extension we are handling.
 EventPool getEventPool()
          Provide a reference to the event pool.
 DispatchQueue getNewDispatchQueueInstance()
          Provide an instance of the specific DispatchQueue we want to use.
 EventBroker getNewEventBrokerInstance()
          Provide an instance of the specific EventBroker we want to use.
 EventGateway getParent()
          Get the parent gateway.
 void handleDefault(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          Handle the default HttpRequest.
 void handleDefaultExt(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, Object externalContextObj)
          Handle the default HttpRequest with the ability to add the provided object into the context.
 void handleEventException(EventException e, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          Handle an EventException.
 void init()
          Here's where we initialize the servlet.
 void initializeLocal()
          Perform any local initialization (this is where you should add any other known EventGateways)
 void initializeLocal(javax.servlet.ServletConfig iconfig)
          Deprecated. If your code is still attempting to extend this old method signature, you need to change it to use initializeLocal() instead. If you still need to get a reference to the servlet config, just call 'this.getServletConfig()'. This method is now final so that code which might still be using it will no longer compile.
static void logRequestDetails(org.apache.log4j.Logger l, org.apache.log4j.Level level)
          This method is used to log param details associated with the current request.
 void register(EventBroker eb)
          Ask all interested parties to register with the EventBroker
 void registerLocalEventAliases(EventBroker eb)
          Register any local event aliases in the EventBroker
 void registerLocalEventInterests(EventBroker eb)
          Register any local interests in the EventBroker
 void remove(EventGateway eg)
          Remove an event gateway from this one
 void setParent(EventGateway eg)
          Set the parent gateway.
 void specifyEventGateways(EventGateway gateway)
          Specify event gateways.
 void specifyLocalEventAliases(Class event)
          Rather than overriding the registerLocalEventAliases method, you can just invoke this method instead for type of event you want to manually alias.
 void specifyLocalEventInterests(ListenerFactory factory)
          Rather than overriding the registerLocalEventInterests method, you can just invoke this method instead for each interest you'd like to register.
 void specifyLocalEventInterests(ListenerFactory factory, Class event)
          Rather than overriding the registerLocalEventInterests method, you can just invoke this method instead for each interest you'd like to register.
protected  javax.servlet.http.HttpServletRequest wrapRequest(javax.servlet.http.HttpServletRequest req)
           
protected  javax.servlet.http.HttpServletResponse wrapResponse(javax.servlet.http.HttpServletResponse resp)
           
 
Methods inherited from class javax.servlet.http.HttpServlet
doHead, 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

USE_EVENT_POOLING

public static boolean USE_EVENT_POOLING

RESPOND_WITH_404

public static boolean RESPOND_WITH_404

REQUEST_WRAPPER

public static RequestWrapper REQUEST_WRAPPER

RESPONSE_WRAPPER

public static ResponseWrapper RESPONSE_WRAPPER

ENABLE_LR_EVENTS

public static boolean ENABLE_LR_EVENTS

LR_OVERRIDE_KEY

public static String LR_OVERRIDE_KEY

HTTP_SERVLET_REQUEST

public static final String HTTP_SERVLET_REQUEST

HTTP_SERVLET_RESPONSE

public static final String HTTP_SERVLET_RESPONSE

THREAD_POOL

public static final String THREAD_POOL

TARGET_EVENT_NAME

public static final String TARGET_EVENT_NAME

EXTERNAL_CONTEXT_OBJ_NAME

public static final String EXTERNAL_CONTEXT_OBJ_NAME

LR_ID

public static final String LR_ID
See Also:
Constant Field Values

LR_OR

public static final String LR_OR
See Also:
Constant Field Values

LR_SOR

public static final String LR_SOR
See Also:
Constant Field Values

eventGateway

protected EventGateway eventGateway

gateways

protected List gateways

virgin

protected boolean virgin
Constructor Detail

ApplicationGateway

public ApplicationGateway()
Public noargs constructor

Method Detail

initializeLocal

public void initializeLocal()

Perform any local initialization (this is where you should add any other known EventGateways)


initializeLocal

public final void initializeLocal(javax.servlet.ServletConfig iconfig)
                           throws javax.servlet.ServletException
Deprecated. If your code is still attempting to extend this old method signature, you need to change it to use initializeLocal() instead. If you still need to get a reference to the servlet config, just call 'this.getServletConfig()'. This method is now final so that code which might still be using it will no longer compile.

Perform any local initialization (this is where you should add any other known EventGateways)

Parameters:
iconfig - the ServletConfig object used to configure this servlet
Throws:
javax.servlet.ServletException

destroyLocal

public void destroyLocal()

Perform any local cleanup (this is where you should remove any known EventGateways)


getNewEventBrokerInstance

public EventBroker getNewEventBrokerInstance()

Provide an instance of the specific EventBroker we want to use. Override this method if you'd like to use something other than the DefaultEventBroker.

Returns:
a new instance of the EventBroker

getNewDispatchQueueInstance

public DispatchQueue getNewDispatchQueueInstance()

Provide an instance of the specific DispatchQueue we want to use. Override this method if you'd like to use something other than the DefaultDispatchQueue.

Returns:
a new instance of the DispatchQueue.

getDispatcherFactory

public DispatcherFactory getDispatcherFactory()

Provide an instance of the specific EventDispatcher we want to use. Override this method if you'd like to use something other than DefaultEventBroker.

Returns:
a new instance of the DispatcherFactory

getEventExtension

public String getEventExtension()

Indicate which event extension we are handling. By default the gateway handles extensions of .event. If you wish to handle a different function you should override this method to return the value defined in the web.xml file.

Returns:
a string defining the event extension handled by this servlet

handleDefault

public void handleDefault(javax.servlet.http.HttpServletRequest req,
                          javax.servlet.http.HttpServletResponse resp)
                   throws javax.servlet.ServletException,
                          IOException

Handle the default HttpRequest. It will probably be rare for developers to override this.

Basically, this method receives a request and attempts to map it to a valid HttpRequestEvent. If the event is invalid, or if the event is NOT an instance of HttpRequestEvent, then we simply create a new instance of HttpRequestEvent and dispatch that instead. This is a very important feature, because it allows us to define events which are not accessible to the outside world -- the gateway will only dispatch HttpRequest events, so you define your publically accessible API by creating an event hierarchy that extends from the HttpRequestEvent object.

Once we have a valid event, we dispatch it. In this case (because this is an Http gateway) we must have a response, so if we catch an UnhandledEventException, we will generate a default error message and return.

Parameters:
req - the servlet request
resp - the servlet response
Throws:
javax.servlet.ServletException
IOException

handleDefaultExt

public void handleDefaultExt(javax.servlet.http.HttpServletRequest req,
                             javax.servlet.http.HttpServletResponse resp,
                             Object externalContextObj)
                      throws javax.servlet.ServletException,
                             IOException

Handle the default HttpRequest with the ability to add the provided object into the context. It will probably be rare for developers to override this.

Basically, this method receives a request and attempts to map it to a valid HttpRequestEvent. If the event is invalid, or if the event is NOT an instance of HttpRequestEvent, then we simply create a new instance of HttpRequestEvent and dispatch that instead. This is a very important feature, because it allows us to define events which are not accessible to the outside world -- the gateway will only dispatch HttpRequest events, so you define your publically accessible API by creating an event hierarchy that extends from the HttpRequestEvent object.

Once we have a valid event, we dispatch it. In this case (because this is an Http gateway) we must have a response, so if we catch an UnhandledEventException, we will generate a default error message and return.

Parameters:
req - the servlet request
resp - the servlet response
externalContextObj - object to put into the context
Throws:
javax.servlet.ServletException
IOException

handleEventException

public void handleEventException(EventException e,
                                 javax.servlet.http.HttpServletRequest req,
                                 javax.servlet.http.HttpServletResponse resp)
                          throws javax.servlet.ServletException,
                                 IOException

Handle an EventException. Basically, this is where we handle the really bad, unexpected type of event exceptions. Generally, as you code, if you want to interrupt the dispatch and fire a new event, you should throw an InterruptDispatchException. Only throw EventExceptions in truly exceptional circumstances.

Parameters:
e - the EventException to handle
req - the servlet request
resp - the servlet response
Throws:
javax.servlet.ServletException
IOException

logRequestDetails

public static void logRequestDetails(org.apache.log4j.Logger l,
                                     org.apache.log4j.Level level)
This method is used to log param details associated with the current request. It is called automatically when Barracuda hits a serious exception; you may wish to call it manually in your own code that extends BaseEventListener


specifyEventGateways

public final void specifyEventGateways(EventGateway gateway)

Specify event gateways. You can call this method with as many different gateways as you like. When the Application Gateway initializes, it will load them all. When the gateway is destroyed, they will be deregistered.

Parameters:
gateway - an event gateway we'd like to have registered

getEventBroker

public final EventBroker getEventBroker()

Provide a reference to the event broker.

Returns:
a reference to the master event broker

getEventPool

public final EventPool getEventPool()

Provide a reference to the event pool. May return null if we're not using event pooling.

Returns:
a reference to the master event pool

wrapRequest

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

wrapResponse

protected javax.servlet.http.HttpServletResponse wrapResponse(javax.servlet.http.HttpServletResponse resp)

setParent

public final void setParent(EventGateway eg)

Set the parent gateway. Null indicates its the root. By definition, an ApplicationGateway is always the root.

Specified by:
setParent in interface EventGateway
Parameters:
eg - the parent event gateway for this gateway

getParent

public final EventGateway getParent()

Get the parent gateway. Returns null if it's the root.

Specified by:
getParent in interface EventGateway
Returns:
the parent event gateway

add

public final void add(EventGateway eg)

Add an event gateway to this one

Specified by:
add in interface EventGateway
Parameters:
eg - the event gateway to be added

remove

public final void remove(EventGateway eg)

Remove an event gateway from this one

Specified by:
remove in interface EventGateway
Parameters:
eg - the event gateway to be removed

getChildren

public List getChildren()
Get a list of child gateways. The list returned is a copy of the underlying child gateway list.

Specified by:
getChildren in interface EventGateway
Returns:
a list of child gateways

register

public final void register(EventBroker eb)

Ask all interested parties to register with the EventBroker

Specified by:
register in interface EventGateway
Parameters:
eb - the event broker to register with

deregister

public final void deregister(EventBroker eb)

Ask all interested parties to de-register with the EventBroker

Specified by:
deregister in interface EventGateway
Parameters:
eb - the event broker to de-register with

registerLocalEventInterests

public final void registerLocalEventInterests(EventBroker eb)
Register any local interests in the EventBroker

Specified by:
registerLocalEventInterests in interface EventGateway
Parameters:
eb - the event broker this gateway should use to register for local events

deregisterLocalEventInterests

public final void deregisterLocalEventInterests(EventBroker eb)
Deregister any local interests in the EventBroker

Specified by:
deregisterLocalEventInterests in interface EventGateway
Parameters:
eb - the event broker this gateway should use to de-register for local events

registerLocalEventAliases

public final void registerLocalEventAliases(EventBroker eb)
Register any local event aliases in the EventBroker

Specified by:
registerLocalEventAliases in interface EventGateway
Parameters:
eb - the event broker this gateway should use to register aliases for local events

specifyLocalEventInterests

public final void specifyLocalEventInterests(ListenerFactory factory)
Rather than overriding the registerLocalEventInterests method, you can just invoke this method instead for each interest you'd like to register. The gateway will keep track of all factories specified, and register/deregister when appropriate (so you don't have to worry about it). Notice that this method registers just the listener id (not for a specific class of event). The only real reason for using the registerLocalEventInterests method would be if you actually need access to the EventBroker. Note that if the event class is not an instance of BaseEvent, the request is just silently ignored (unlike the event broker, which throws an exception).

Specified by:
specifyLocalEventInterests in interface EventGateway
Parameters:
factory - the factory we wish to register with the event broker

specifyLocalEventInterests

public final void specifyLocalEventInterests(ListenerFactory factory,
                                             Class event)
Rather than overriding the registerLocalEventInterests method, you can just invoke this method instead for each interest you'd like to register. The gateway will keep track of all factories specified, and register/deregister when appropriate (so you don't have to worry about it). The only real reason for using the registerLocalEventInterests method would be if you actually need access to the EventBroker. Note that if the event class is not an instance of BaseEvent, the request is just silently ignored (unlike the event broker, which throws an exception).

Specified by:
specifyLocalEventInterests in interface EventGateway
Parameters:
factory - the factory we wish to register with the event broker
event - the class of events we are interested in

specifyLocalEventAliases

public final void specifyLocalEventAliases(Class event)
Rather than overriding the registerLocalEventAliases method, you can just invoke this method instead for type of event you want to manually alias. The only real reason for using the registerLocalEventAliases method would be if you actually need access to the EventBroker. Note that if the event class is not an instance of BaseEvent, the request is just silently ignored (unlike the event broker, which throws an exception).

Specified by:
specifyLocalEventAliases in interface EventGateway
Parameters:
event - the class of events we are interested in registering aliases for

doGet

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

By default the GET request is mapped to the handleDefault method

Overrides:
doGet in class javax.servlet.http.HttpServlet
Parameters:
req - the servlet request
resp - the servlet response
Throws:
javax.servlet.ServletException
IOException

doPost

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

By default the POST request is mapped to the handleDefault method

Overrides:
doPost in class javax.servlet.http.HttpServlet
Parameters:
req - the servlet request
resp - the servlet response
Throws:
javax.servlet.ServletException
IOException

doOptions

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

By default the OPTIONS request is mapped to the handleDefault method

Overrides:
doOptions in class javax.servlet.http.HttpServlet
Parameters:
req - the servlet request
resp - the servlet response
Throws:
javax.servlet.ServletException
IOException

doDelete

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

By default the DELETE request is mapped to the handleDefault method

Overrides:
doDelete in class javax.servlet.http.HttpServlet
Parameters:
req - the servlet request
resp - the servlet response
Throws:
javax.servlet.ServletException
IOException

doPut

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

By default the PUT request is mapped to the handleDefault method

Overrides:
doPut in class javax.servlet.http.HttpServlet
Parameters:
req - the servlet request
resp - the servlet response
Throws:
javax.servlet.ServletException
IOException

doTrace

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

By default the TRACE request is mapped to the handleDefault method

Overrides:
doTrace in class javax.servlet.http.HttpServlet
Parameters:
req - the servlet request
resp - the servlet response
Throws:
javax.servlet.ServletException
IOException

init

public void init()
          throws javax.servlet.ServletException

Here's where we initialize the servlet.

Overrides:
init in class javax.servlet.GenericServlet
Throws:
javax.servlet.ServletException

destroy

public void destroy()

Here's where we destroy the servlet.

Specified by:
destroy in interface javax.servlet.Servlet
Overrides:
destroy in class javax.servlet.GenericServlet


Copyright © 2006 BarracudaMVC.org All Rights Reserved.