org.enhydra.barracuda.core.event
Class ApplicationGateway

java.lang.Object
  |
  +--javax.servlet.GenericServlet
        |
        +--javax.servlet.http.HttpServlet
              |
              +--org.enhydra.barracuda.core.event.ApplicationGateway
All Implemented Interfaces:
EventGateway, java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig
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.enhydra.barracuda.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
protected  DefaultEventGateway defaultEventGateway
           
static java.lang.String EXTERNAL_CONTEXT_OBJ_NAME
           
protected  java.util.List gateways
           
protected static org.apache.log4j.Logger logger
           
static RequestWrapper REQUEST_WRAPPER
           
static boolean SHOW_APP_STRUCTURE
           
static java.lang.String TARGET_EVENT_NAME
           
static boolean USE_EVENT_POOLING
           
 
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 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 res)
          By default the TRACE request is mapped to the handleDefault method
 java.util.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.
 java.lang.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.
 EventPool getNewEventPoolInstance()
          Provide an instance of the specific EventPool 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, java.lang.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.
 void register(EventBroker eb)
          Ask all interested parties to register with 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.
 
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

SHOW_APP_STRUCTURE

public static boolean SHOW_APP_STRUCTURE

logger

protected static org.apache.log4j.Logger logger

TARGET_EVENT_NAME

public static final java.lang.String TARGET_EVENT_NAME
See Also:
Constant Field Values

EXTERNAL_CONTEXT_OBJ_NAME

public static final java.lang.String EXTERNAL_CONTEXT_OBJ_NAME
See Also:
Constant Field Values

REQUEST_WRAPPER

public static RequestWrapper REQUEST_WRAPPER

defaultEventGateway

protected DefaultEventGateway defaultEventGateway

gateways

protected java.util.List gateways
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)

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

getNewEventPoolInstance

public EventPool getNewEventPoolInstance()

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

Returns:
a new instance of the EventPool.

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 java.lang.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,
                          java.io.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
Throws:
javax.servlet.ServletException
java.io.IOException

handleDefaultExt

public void handleDefaultExt(javax.servlet.http.HttpServletRequest req,
                             javax.servlet.http.HttpServletResponse resp,
                             java.lang.Object externalContextObj)
                      throws javax.servlet.ServletException,
                             java.io.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
Throws:
javax.servlet.ServletException
java.io.IOException

handleEventException

public void handleEventException(EventException e,
                                 javax.servlet.http.HttpServletRequest req,
                                 javax.servlet.http.HttpServletResponse resp)
                          throws javax.servlet.ServletException,
                                 java.io.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:
req - the servlet request
Throws:
javax.servlet.ServletException
java.io.IOException

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

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 java.util.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

doGet

protected void doGet(javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse resp)
              throws javax.servlet.ServletException,
                     java.io.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
java.io.IOException

doPost

protected void doPost(javax.servlet.http.HttpServletRequest req,
                      javax.servlet.http.HttpServletResponse resp)
               throws javax.servlet.ServletException,
                      java.io.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
java.io.IOException

doOptions

protected void doOptions(javax.servlet.http.HttpServletRequest req,
                         javax.servlet.http.HttpServletResponse resp)
                  throws javax.servlet.ServletException,
                         java.io.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
java.io.IOException

doDelete

protected void doDelete(javax.servlet.http.HttpServletRequest req,
                        javax.servlet.http.HttpServletResponse resp)
                 throws javax.servlet.ServletException,
                        java.io.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
java.io.IOException

doPut

protected void doPut(javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse resp)
              throws javax.servlet.ServletException,
                     java.io.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
java.io.IOException

doTrace

protected void doTrace(javax.servlet.http.HttpServletRequest req,
                       javax.servlet.http.HttpServletResponse res)
                throws javax.servlet.ServletException,
                       java.io.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
Throws:
javax.servlet.ServletException
java.io.IOException

init

public void init()
          throws javax.servlet.ServletException

Here's where we initialize the servlet.

Overrides:
init in class javax.servlet.GenericServlet
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 © 2001 Enhydra.org