oracle.cabo.servlet
Class AbstractPageBroker

java.lang.Object
  |
  +--oracle.cabo.servlet.AbstractPageBroker

All Implemented Interfaces:

PageBroker

Direct Known Subclasses:

BaseUIPageBroker, JspPageBroker

public abstract class AbstractPageBroker

extends java.lang.Object

implements PageBroker

AbstractPageBroker provides a default implementation of the PageBroker interface. It supports explicit registration of per-page PageDescriptions, each of which encapsulates an event handler and a renderer, as well as the specification of default and login pages.

AbstractPageBroker uses the following servlet configuration parameters:

• oracle.cabo.servlet.event.PageFlowEngine: The class name of the PageFlowEngine (defaults to the TrivialPageFlowEngine)
• oracle.cabo.servlet.defaultPage: The name of the default page
• oracle.cabo.servlet.errorPage: The name of the error page
• oracle.cabo.servlet.loginPage: The name of the login page
• oracle.cabo.servlet.loggedInKey: A key to check for being logged in (see below)
• oracle.cabo.servlet.io.FileUploadManager: The class name of the FileUploadManager

By default, if a login page has been set, the user will be required to login before accessing any other page. This behavior can be changed by attaching a new PageFlowEngine. For example, clients can subclass the default engine, TrivialPageFlowEngine, and override needsLogin(). In addition, if "oracle.cabo.servlet.loggedInKey" has been set in the Servlet configuration parameters, then the user will be considered logged in if the HttpSession parameter with this key is non-null.

Multipart requests

AbstractPageBroker includes built-in support for HTTP multipart requests, the requests used to upload files. By default, the servlet will automatically rip through any multipart request, extracting simple name/value pairs and calling the protected doUploadFile() method once for each contained file. The parameters in the multipart request and the parameters embedded in the URL's query string will be assembled into a single PageEvent.

Some clients may not want file uploading handled at this level; all this processing happens before the PageBroker is called at all. There are three ways to turn off this automatic handling.

• Add an "event" query parameter to the URL. If this is included, the query parameters will be assembled into a PageEvent, and the multipart request itself will be ignored. A client's event handler can then use the UIX Controller (Baja) MultipartFormHandler to manually process the request. With this approach, any parameters not directly encoded into the HTML form's "action" URL will not be available until the multipart request is processed.
• Override AbstractPageBroker.shouldHandleUploadFile() to return false. A PageEvent will still be built if there is an "event" query parameter, but otherwise the event will be null.
• Specify a custom FileUploadManager to manage processing of multipart form items during file upload.

See Also:

PageFlowEngine, MultipartFormHandler

Field Summary

static java.lang.String

EVENT_ERROR_KEY Key used to store on the ServletRequest any Throwable or Exception produced by an EventHandler.

Constructor Summary

AbstractPageBroker()
Creates an AbstractPageBroker.

Method Summary

PageEvent	decodeMultipartRequest(BajaContext context, Page page) Handle a multipart request.
void	destroy() Destroys the page broker, freeing any state as needed.
protected java.lang.String	doUploadFile(BajaContext context, Page page, MultipartFormItem item) Handler for uploading a file.
Page	getDefaultPage() Returns the default page.
Page	getErrorPage() Returns the error page.
protected Page	getErrorPage(BajaContext context, java.lang.Throwable error) Called by renderError() to convert an error into a Page for rendering.
static java.lang.Throwable	getEventError(BajaContext context) Returns the Throwable that was thrown from an EventHandler in the current request.
protected EventHandler	getEventHandler(BajaContext context, Page page, PageEvent event) Returns the event handler that should be used for the specified page and page event.
FileUploadManager	getFileUploadManager() Returns the FileUploadManager used to process multipart requests on this broker.
protected PageDescription	getPageDescription(BajaContext context, Page page) Called to retrive a page description.
PageFlowEngine	getPageFlowEngine() Returns the PageFlowEngine used to process event results on this broker.
protected PageRenderer	getPageRenderer(BajaContext context, Page page) Returns the renderer that should be used for the specified page.
java.lang.Object	getService(BajaContext context, java.lang.Class serviceClass, java.lang.Object serviceSelector) Returns a object that provides some global service.
javax.servlet.Servlet	getServlet() Returns the servlet this page broker is attached to.
Page	handleRequest(BajaContext context, Page page, PageEvent event) Process a request for a single page, returning the new page to display.
void	init(javax.servlet.Servlet servlet, javax.servlet.ServletConfig config) Initializes the page broker.
protected boolean	isCacheable(BajaContext context, Page page, java.lang.Throwable error, PageEvent event) Called to determine if the page about to be rendered is cacheable.
boolean	isEmbedded() Returns whether UIX Controller (Baja) is being used in "embedded" mode.
void	registerGlobalEventHandler(java.lang.String eventName, EventHandler handler) Registers an event handler for use on all pages.
void	registerPageDescription(java.lang.String pageName, PageDescription description) Registers a page description.
void	registerPageDescription(java.lang.String pageName, PageRenderer renderer, EventHandler eventHandler) Registers a page description.
void	renderError(BajaContext context, java.lang.Throwable error) Renders an error.
void	renderPage(BajaContext context, Page page) Renders a page.
void	requestEnded(BajaContext context) Callback at the very end of a request.
void	requestStarted(BajaContext context) Called at the very beginning of a request.
void	resetGlobalEventHandlers() Unregisters all global event handlers.
void	resetPageDescriptions() Unregisters all page descriptions.
void	setDefaultPage(Page page) Sets the default page.
void	setEmbedded(boolean embedded) Sets whether the UIX Controller (Baja) is being used in "embedded" mode.
void	setErrorPage(Page page) Sets the error page.
void	setFileUploadManager(FileUploadManager fileUpload) Sets the FileUploadManager used to process multipart requests on this broker.
void	setPageFlowEngine(PageFlowEngine pageFlow) Sets the PageFlowEngine used to process event results on this broker.
protected void	setResponseHeaders(BajaContext context, Page page, java.lang.Throwable error, PageEvent event) Sets response headers on the page.
protected boolean	shouldHandleUploadFile(BajaContext context, Page page) Returns true if a current multipart request will be handled automatically by the PageBroker.
void	unregisterGlobalEventHandler(java.lang.String eventName) Unregisters an event handler for use on all pages.
void	unregisterPageDescription(java.lang.String pageName) Unregisters a page description.

Methods inherited from class java.lang.Object

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

Field Detail

EVENT_ERROR_KEY

public static final java.lang.String EVENT_ERROR_KEY

Key used to store on the ServletRequest any Throwable or Exception produced by an EventHandler.

See Also:

getEventError(oracle.cabo.servlet.BajaContext)

Constructor Detail

AbstractPageBroker

public AbstractPageBroker()

Creates an AbstractPageBroker.

Method Detail

getServlet

public javax.servlet.Servlet getServlet()

Returns the servlet this page broker is attached to. This method will return null until after init() has been called.

getDefaultPage

public Page getDefaultPage()

Returns the default page. This page will be used for URL's without any name information (i.e., with just the servlet URL).

setDefaultPage

public void setDefaultPage(Page page)

Sets the default page. This page will be used for URL's without any name information (i.e., with just the servlet URL).

getEventError

public static java.lang.Throwable getEventError(BajaContext context)

Returns the Throwable that was thrown from an EventHandler in the current request. Pages that do not have a BajaContext can use the EVENT_ERROR_KEY to retrieve the Throwable as a ServletRequest attribute.

See Also:

EVENT_ERROR_KEY

getErrorPage

public Page getErrorPage()

Returns the error page. This page will be used when an event handler throws an exception that is not otherwised consumed or handled.

setErrorPage

public void setErrorPage(Page page)

Sets the error page. This page will be used when an event handler throws an exception that is not otherwised consumed or handled.

getPageFlowEngine

public PageFlowEngine getPageFlowEngine()

Returns the PageFlowEngine used to process event results on this broker.

setPageFlowEngine

public void setPageFlowEngine(PageFlowEngine pageFlow)

Sets the PageFlowEngine used to process event results on this broker.

getFileUploadManager

public FileUploadManager getFileUploadManager()

Returns the FileUploadManager used to process multipart requests on this broker.

setFileUploadManager

public void setFileUploadManager(FileUploadManager fileUpload)

Sets the FileUploadManager used to process multipart requests on this broker.

isEmbedded

public boolean isEmbedded()

Returns whether UIX Controller (Baja) is being used in "embedded" mode.

See Also:

setEmbedded(boolean)

setEmbedded

public void setEmbedded(boolean embedded)

Sets whether the UIX Controller (Baja) is being used in "embedded" mode. When used in this way, the UIX Controller will not set any response headers. In addition, pieces of the UIX Controller that output HTML will not automatically add <HTML>, <HEAD>, or <BODY> sections. So, for example, UIX developers do not automatically get the "stylesheet" section (and in fact the entire <head> section will be ignored).

registerPageDescription

public void registerPageDescription(java.lang.String pageName,
                                    PageDescription description)

Registers a page description.

Parameters:

pageName - the name of the page

description - a PageDescription implementation

registerPageDescription

public void registerPageDescription(java.lang.String pageName,
                                    PageRenderer renderer,
                                    EventHandler eventHandler)

Registers a page description.

Parameters:

pageName - the name of the page

renderer - a PageRenderer for the page

eventHandler - an event handler

unregisterPageDescription

public void unregisterPageDescription(java.lang.String pageName)

Unregisters a page description.

Parameters:

pageName - the name of the page

resetPageDescriptions

public void resetPageDescriptions()

Unregisters all page descriptions.

registerGlobalEventHandler

public void registerGlobalEventHandler(java.lang.String eventName,
                                       EventHandler handler)

Registers an event handler for use on all pages.

Parameters:

eventName - the name of the event

handler - an event handler for that page

unregisterGlobalEventHandler

public void unregisterGlobalEventHandler(java.lang.String eventName)

Unregisters an event handler for use on all pages.

Parameters:

eventName - the name of the event

resetGlobalEventHandlers

public void resetGlobalEventHandlers()

Unregisters all global event handlers.

requestStarted

public void requestStarted(BajaContext context)
                    throws javax.servlet.ServletException

Called at the very beginning of a request. Called before any other methods, and before decoding has commenced.

Specified by:

requestStarted in interface PageBroker

Parameters:

context - the BajaContext

requestEnded

public void requestEnded(BajaContext context)
                  throws javax.servlet.ServletException

Callback at the very end of a request. Called after all other methods and after the page has finished rendering, and called whether or not the request succeeded successfully or terminated with an error or exception.

Specified by:

requestEnded in interface PageBroker

Parameters:

context - the BajaContext

handleRequest

public Page handleRequest(BajaContext context,
                          Page page,
                          PageEvent event)
                   throws PageEventException

Process a request for a single page, returning the new page to display. The default implementation will forward the request to either the default or login page, if needed, and then send the event (if it exists) to the event handler registered for that page. If forwarded to the login page, the login page will have the original request page set as a FORWARD_PAGE_PROPERTY, and the original event set as a FORWARD_EVENT_PROPERTY.

Specified by:

handleRequest in interface PageBroker

Parameters:

context - the BajaContext

page - the page the client is requesting

event - the event on that page, or null if the client is just requesting a page display

Throws:

PageEventException - if the processing of the event fails

decodeMultipartRequest

public PageEvent decodeMultipartRequest(BajaContext context,
                                        Page page)
                                 throws java.io.IOException,
                                        javax.servlet.ServletException

Handle a multipart request. An implementation can use MultipartFormHandler to decode the request. Alternatively, the method could be implemented to do nothing, in which case a client would

Specified by:

decodeMultipartRequest in interface PageBroker

Parameters:

context - the BajaContext

page - the page the client is requesting

Returns:

the PageEvent to be processed in response

See Also:

MultipartFormHandler

renderPage

public void renderPage(BajaContext context,
                       Page page)
                throws java.io.IOException,
                       javax.servlet.ServletException

Renders a page.

Specified by:

renderPage in interface PageBroker

Parameters:

context - the BajaContext

page - the page returned from handleRequest

renderError

public void renderError(BajaContext context,
                        java.lang.Throwable error)
                 throws java.io.IOException,
                        javax.servlet.ServletException

Renders an error.

Specified by:

renderError in interface PageBroker

Parameters:

context - the BajaContext

error - a Throwable

getService

public java.lang.Object getService(BajaContext context,
                                   java.lang.Class serviceClass,
                                   java.lang.Object serviceSelector)

Returns a object that provides some global service. The default implementation of BajaContext.getService() will call this PageBroker method for any services it doesn't serve itself. Clients can override this method to return any such service. AbstractPageBroker supports:

• PageDescription: selector must be a Page object

Specified by:

getService in interface PageBroker

Parameters:

context - the BajaContext

serviceClass - a class object that the returned object must be an instance of

serviceSelector - a selector object, if one is needed

init

public void init(javax.servlet.Servlet servlet,
                 javax.servlet.ServletConfig config)
          throws javax.servlet.ServletException

Initializes the page broker. Subclasses must call super.init(servlet, config) if they override this method.

Specified by:

init in interface PageBroker

destroy

public void destroy()

Destroys the page broker, freeing any state as needed. Subclasses must call super.destroy() if they override this method.

Specified by:

destroy in interface PageBroker

setResponseHeaders

protected void setResponseHeaders(BajaContext context,
                                  Page page,
                                  java.lang.Throwable error,
                                  PageEvent event)

Sets response headers on the page. The default behavior is to call isCacheable(); if that function returns false, cacheing of the page is blocked by setting the "Cache-Control", "Pragma", and "Expires" HTTP headers.

Parameters:

context - the BajaContext

page - the page that will be displayed - i.e., the Page object returned from the EventHandler, or null if an exception was thrown

error - the exception thrown by the EventHandler, if any

event - the event that was passed to that handler

isCacheable

protected boolean isCacheable(BajaContext context,
                              Page page,
                              java.lang.Throwable error,
                              PageEvent event)

Called to determine if the page about to be rendered is cacheable. The default behavior is to return "true" only if the event is null (or the event name is null) and the error is null.

Parameters:

context - the BajaContext

page - the page that will be displayed - i.e., the Page object returned from the EventHandler, or null if an exception was thrown

error - the exception thrown by the EventHandler, if any

event - the event that was passed to that handler

getErrorPage

protected Page getErrorPage(BajaContext context,
                            java.lang.Throwable error)

Called by renderError() to convert an error into a Page for rendering. If this method returns a non-null Page renderError() will automatically call renderPage() with that Page. By default, this method returns the error page set with setErrorPage().

getPageDescription

protected PageDescription getPageDescription(BajaContext context,
                                             Page page)

Called to retrive a page description.

getEventHandler

protected EventHandler getEventHandler(BajaContext context,
                                       Page page,
                                       PageEvent event)

Returns the event handler that should be used for the specified page and page event. This method returns handlers in the following order:

1. Handlers registered by both event name and (non-null) page name
2. Handlers registered by page name alone
3. Handlers registered by event name (with a null page name)

Parameters:

event - maybe null to indicate that no event was fired. In this case a null event handler (if registered) for the page is returned before returning any handlers registered by page name alone.

getPageRenderer

protected PageRenderer getPageRenderer(BajaContext context,
                                       Page page)

Returns the renderer that should be used for the specified page. The default implementation gets the PageRenderer from a PageDescription.

shouldHandleUploadFile

protected boolean shouldHandleUploadFile(BajaContext context,
                                         Page page)

Returns true if a current multipart request will be handled automatically by the PageBroker. This implementation returns "true" if:

• The request is a multipart POST
• The request does not have an "event" parameter directly in the URL

doUploadFile

protected java.lang.String doUploadFile(BajaContext context,
                                        Page page,
                                        MultipartFormItem item)
                                 throws java.io.IOException

Handler for uploading a file. By default, each upload is dropped. Clients that need to support file upload should override this method to process the MultipartFormItem. The return value of this function will be added to the PageEvent; if clients need further processing of the item in subsequent handling of the page, they should return a meaningful string after reading the file.

Parameters:

context - the BajaContext for this request

page - the page the file is being uploaded from; this page object has not yet been validated for login or any other handling

item - a MultipartFormItem that can be used to retrieve the file

Returns:

a value that will be inserted into the PageEvent as a substitute for the actual file contents.