com.ashridgetech.gen2j.web
Class JspManager

java.lang.Object
  |
  +--com.ashridgetech.gen2j.web.JspManager

public class JspManager

extends Object

Manages the display of a main object and its sub-objects using one main JSP and multiple nested JSPs. It is intended to be used by the Gen2J object tag but it could also be used on its own. Before each sub-object is visited, it is added to the "stack" of objects by calling visitProperty(javax.servlet.ServletRequest, java.lang.String), and after displaying it, leaveProperty(javax.servlet.ServletRequest) must be called. The findJsp(java.lang.String, javax.servlet.ServletRequest) method gives the name of the appropriate JSP to display the current object. There is intended to be one instance of this class stored as a request scope attribute for each HTTP request. Create this instance in the main JSP page for the response by calling createInstance(javax.servlet.ServletRequest) and access it in sub-pagesgetInstance(javax.servlet.ServletRequest).

JspManager is intended to support the use of Struts bean and html tags. It ensures the object currently being displayed is available in request scope under the attribute name defined by JSP_MANAGER_KEY. It detects when a Struts html:form tag is being processed, and provides item names relative to the form bean with the formItemName(javax.servlet.ServletRequest, java.lang.String) method.

Version:

1.0

Author:

Paul Boocock

Field Summary

static String	CURRENT_BEAN_KEY The attribute name with which the object currently being displayed is stored in request scope.
static String	JSP_MANAGER_KEY The attribute name with which the JspManager for the current request is stored in request scope.
static String	MAIN_OBJECT_KEY The attribute name with which the main object for the current request must be stored in request scope before createInstance( javax.servlet.ServletRequest ) is called.
static String	PACKAGE_NAME
static String	STANDARD_PAGE_JSP The standard page JSP name - set to "page.jsp"
static String	STRUTS_FORM_BEAN_KEY
static String	UCM_NAME_PART
static String	VIEW_NAME_PARAM The request parameter name for the view of the main object of the current request.

Method Summary

static JspManager	createInstance(javax.servlet.ServletRequest request) Create the instance of JspManager for the current ServletRequest.
static JspManager	createInstance(javax.servlet.ServletRequest request, Object mainObject) Create the instance of JspManager for the current ServletRequest.
boolean	currentCollectionHasNext() Indicate whether the current collection has more elements.
String	findFormItemName(javax.servlet.ServletRequest request, String propertyName) Get the name of a property, expanded to be relative to the current form object, as marked by markFormLevel().
String	findJsp(String viewName, javax.servlet.ServletRequest request) Find the name of the correct JSP to display the current object.
static String	findPageJsp(javax.servlet.ServletRequest request) Find the name of the correct JSP to display the an HTML page around the top-level object.
static String	formItemName(javax.servlet.ServletRequest request, String propertyName) Get the name of a property, expanded to be relative to the current form object, from the JspManager for the current request.
Object	getCurrentElement() Get the current element being displayed from the current collection object.
int	getCurrentIndex() Get the index of the current element being displayed from the current collection.
Object	getCurrentObject() Get the current object being displayed.
Object	getCurrentObjectOrElement() Get EITHER the current object being displayed OR the current element if it is a collection and visitNextElement(javax.servlet.ServletRequest) has been called.
static JspManager	getInstance(javax.servlet.ServletRequest request) Get the instance of JspManager for the current ServletRequest.
Object	getMainObject() Get the main (top-level) object for this UCM.
String	getPageTitle() Get the page title.
static Object	getProperty(Object bean, String propertyName) Find a property of a bean identified by the given nested/indexed Struts-style property name.
boolean	isCurrentAtTopLevel() Indicate whether the current object is the main object.
boolean	isCurrentObjectCollection() Indicate whether the current object being displayed is a collection.
void	leaveProperty(javax.servlet.ServletRequest request) Called after finishing the display of a sub-object.
void	markFormLevel() Mark the current object as one being displayed by an HTML form tag.
static String	pageTitle(javax.servlet.ServletRequest request) Get the page title for the current requests's JspManager.
void	setPageTitle(String title) Set the page title.
void	visitNextElement(javax.servlet.ServletRequest request) Prepare to display a sub-object which is the next element of the current collection object.
void	visitProperty(javax.servlet.ServletRequest request, String name) Prepare to display a sub-object which is a property of the current object.

Methods inherited from class java.lang.Object

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

Field Detail

PACKAGE_NAME

public static final String PACKAGE_NAME

STANDARD_PAGE_JSP

public static final String STANDARD_PAGE_JSP

The standard page JSP name - set to "page.jsp"

MAIN_OBJECT_KEY

public static final String MAIN_OBJECT_KEY

The attribute name with which the main object for the current request must be stored in request scope before createInstance( javax.servlet.ServletRequest ) is called.

VIEW_NAME_PARAM

public static final String VIEW_NAME_PARAM

The request parameter name for the view of the main object of the current request.

JSP_MANAGER_KEY

public static final String JSP_MANAGER_KEY

The attribute name with which the JspManager for the current request is stored in request scope.

STRUTS_FORM_BEAN_KEY

public static final String STRUTS_FORM_BEAN_KEY

CURRENT_BEAN_KEY

public static final String CURRENT_BEAN_KEY

The attribute name with which the object currently being displayed is stored in request scope. Set to currentBean.

UCM_NAME_PART

public static final String UCM_NAME_PART

Method Detail

createInstance

public static JspManager createInstance(javax.servlet.ServletRequest request)
                                 throws javax.servlet.ServletException

Create the instance of JspManager for the current ServletRequest. This method must only be called once, before getInstance(javax.servlet.ServletRequest) is called. to create and store a JspManager. The main object for this JspManager must have previously been stored in request scope with the name defined by MAIN_OBJECT_KEY.

Parameters:

mainObject - the main Object being displayed in response to the current request. Becomes the current object of this JspManager

Returns:

the new JspManager for the current request

Throws:

javax.servlet.ServletException - if there is already a JspManager for the current request, or if request or mainObject are null.

createInstance

public static JspManager createInstance(javax.servlet.ServletRequest request,
                                        Object mainObject)
                                 throws javax.servlet.ServletException

Create the instance of JspManager for the current ServletRequest. This method must only be called once, before getInstance(javax.servlet.ServletRequest) is called. to create and store a JspManager. Sets the page title to the request URL.

Parameters:

request - the ServletRequest currently being processed

mainObject - the main Object being displayed in response to the current request. Becomes the current object of this JspManager

Returns:

the new JspManager for the current request

Throws:

javax.servlet.ServletException - if there is already a JspManager for the current request, or if request or mainObject are null.

getInstance

public static JspManager getInstance(javax.servlet.ServletRequest request)
                              throws javax.servlet.ServletException

Get the instance of JspManager for the current ServletRequest. This method must not be called before one of the createInstance(javax.servlet.ServletRequest) methods has been called to create and store a JspManager.

Parameters:

request - the ServletRequest currently being processed

Returns:

the JspManager for the current request

Throws:

javax.servlet.ServletException - if there is no JspManager for the current request

visitProperty

public void visitProperty(javax.servlet.ServletRequest request,
                          String name)
                   throws javax.servlet.ServletException

Prepare to display a sub-object which is a property of the current object. Makes the sub-object visited the new current object, and stores it as a request scope attribute with the name defined by JSP_MANAGER_KEY.

Parameters:

name - the name of the property

Throws:

javax.servlet.ServletException - if the current object is null, or the property cannot be accessed

leaveProperty

public void leaveProperty(javax.servlet.ServletRequest request)
                   throws javax.servlet.ServletException

Called after finishing the display of a sub-object. Makes the parent of the sub-object just visited the current object again, and stores it as a request scope attribute with the name defined by JSP_MANAGER_KEY.

Throws:

javax.servlet.ServletException - if no property is being visited

visitNextElement

public void visitNextElement(javax.servlet.ServletRequest request)
                      throws javax.servlet.ServletException

Prepare to display a sub-object which is the next element of the current collection object. Makes the element visited the current element, as returned by getCurrentElement() and stores it as a request scope attribute with the name defined by JSP_MANAGER_KEY.

Throws:

javax.servlet.ServletException - if the current object is null, or the current object is not a collection, or there are no more elements

getMainObject

public Object getMainObject()

Get the main (top-level) object for this UCM.

Returns:

the main object

isCurrentAtTopLevel

public boolean isCurrentAtTopLevel()

Indicate whether the current object is the main object.

Returns:

true if the current object is the main object.

See Also:

getMainObject(), getCurrentObject()

getCurrentObject

public Object getCurrentObject()

Get the current object being displayed. Also available as a request scope attribute under the name defined by CURRENT_BEAN_KEY, EXCEPT while visiting the elements of a collection, when each element is stored under the name defined by CURRENT_BEAN_KEY.

Returns:

the current object

getCurrentObjectOrElement

public Object getCurrentObjectOrElement()
                                 throws javax.servlet.ServletException

Get EITHER the current object being displayed OR the current element if it is a collection and visitNextElement(javax.servlet.ServletRequest) has been called. Also available as a request scope attribute under the name defined by CURRENT_BEAN_KEY.

Returns:

the current object or element

getCurrentElement

public Object getCurrentElement()
                         throws javax.servlet.ServletException

Get the current element being displayed from the current collection object. Also available as a request scope attribute under the name defined by CURRENT_BEAN_KEY. Must not be called before visitNextElement(javax.servlet.ServletRequest) has been called for the current object.

Returns:

the current element of the current collection object

Throws:

javax.servlet.ServletException - if the current object is not a collection, or visitNextElement(javax.servlet.ServletRequest) has not been called yet

isCurrentObjectCollection

public boolean isCurrentObjectCollection()

Indicate whether the current object being displayed is a collection.

Returns:

true if the current object is a collection

currentCollectionHasNext

public boolean currentCollectionHasNext()
                                 throws javax.servlet.ServletException

Indicate whether the current collection has more elements.

Returns:

true if the current object has more elements

getCurrentIndex

public int getCurrentIndex()
                    throws javax.servlet.ServletException

Get the index of the current element being displayed from the current collection.

Returns:

true if the current object has more elements

markFormLevel

public void markFormLevel()
                   throws javax.servlet.ServletException

Mark the current object as one being displayed by an HTML form tag. If a Struts html:form tag is used, this will be detected automatically. When this object is left with leaveProperty(javax.servlet.ServletRequest), the form level mark is cleared.

Throws:

javax.servlet.ServletException - if the form level has already been marked

findFormItemName

public String findFormItemName(javax.servlet.ServletRequest request,
                               String propertyName)
                        throws javax.servlet.ServletException

Get the name of a property, expanded to be relative to the current form object, as marked by markFormLevel(). This gives the correct name for use as the property attribute of Struts html tags. If there is no current form-level marked, the name is relative to the main object passed to createInstance(javax.servlet.ServletRequest). if the current object is the form-level object, the same name is returned.

For example, if the form level object is the one which contains the current object, and the current object is called "address", and propertyName is "postCode", then the expanded name returned is "address.postCode".

Parameters:

propertyName - the name of the property

Returns:

the expanded property name

Throws:

javax.servlet.ServletException - if an error occurs

formItemName

public static String formItemName(javax.servlet.ServletRequest request,
                                  String propertyName)
                           throws javax.servlet.ServletException

Get the name of a property, expanded to be relative to the current form object, from the JspManager for the current request.

Parameters:

request - used to find the current JspManager

propertyName - the name of the property

Returns:

the expanded property name

Throws:

javax.servlet.ServletException - if an error occurs

See Also:

findFormItemName(javax.servlet.ServletRequest, java.lang.String)

findJsp

public String findJsp(String viewName,
                      javax.servlet.ServletRequest request)
               throws javax.servlet.ServletException

Find the name of the correct JSP to display the current object. This is the name of the object's class, with '_' and the view name appended if viewName is not null, and then ".jsp" appended. if the class name contains 'UCM', then only the part of the name before that is used. This is to help use with objects derived from classes in the com.ashridgetech.gen2j.ucm package.

Parameters:

viewName - the name of the view - may be null for the default view

Returns:

the JSP name

Throws:

javax.servlet.ServletException - if the current object is null

findPageJsp

public static String findPageJsp(javax.servlet.ServletRequest request)

Find the name of the correct JSP to display the an HTML page around the top-level object. This page should include a <gen2j:object/> tag.

Returns:

the JSP name

getPageTitle

public String getPageTitle()

Get the page title.

Returns:

the page title

setPageTitle

public void setPageTitle(String title)

Set the page title.

Parameters:

title - the page title

pageTitle

public static String pageTitle(javax.servlet.ServletRequest request)
                        throws javax.servlet.ServletException

Get the page title for the current requests's JspManager.

Parameters:

request - the current request being processed

Returns:

the page title

getProperty

public static Object getProperty(Object bean,
                                 String propertyName)
                          throws javax.servlet.ServletException

Find a property of a bean identified by the given nested/indexed Struts-style property name. Trap all exceptions and rethrow as ServletExceptions.

Parameters:

bean - the object in which the property is to be found

propertyName - the name (may be Struts nested/indexed) of the required property

Returns:

the property object

Throws:

javax.servlet.ServletException - if a reflection error occurs