com.iplanet.jato.view
Interface ViewBean

All Superinterfaces:
ContainerView, RequestHandler, RequestParticipant, View, WebActionHandler, WebActions
All Known Implementing Classes:
ViewBeanBase

public interface ViewBean
extends ContainerView, RequestHandler, WebActionHandler

A ViewBean is the peer of a JSP page, and the main View implementation that supports rendering of a JSP. View beans are the main objects named in the JSP's useBean directive, and are directly manipulated by both the JSP and the application servlet. View beans are alternatively known as worker beans or helper beans.

View beans are the main objects used in an application to load and serve other pages, and the methods in this interface are primarily concerned with this task. They provide the very thin but necessary infrastructure between the application and the servlet container. For example, the methods in this interface ensure that if users obtain an instance of a view bean and customize it for the next page display, that same instance will be available to the target JSP. Developers could perform such tasks themselves, but these methods provide a convenient and consistent mechanism.

Developers should obtain instances of view beans using the ViewBeanManager available in the current request context. The advantage of using the ViewBeanManager is that instances of a given view bean can be shared between multiple portions of application code without explicitly passing the instance around. In general, we discourage creation of view beans directly.

Version:
JATO/1.2.2 $Id: ViewBean.java,v 1.21 2002/03/16 03:26:41 todd Exp $

Field Summary
static java.lang.String PAGE_SESSION_ATTRIBUTE_NVP_NAME
          The key used to store page "session" attributes in the HTML page
static java.lang.String VIEW_BEAN_NAME_SUFFIX
           
 
Fields inherited from interface com.iplanet.jato.view.View
QUALIFIED_VIEW_NAME_SEPARATOR
 
Fields inherited from interface com.iplanet.jato.view.WebActionHandler
DELETE_CONTEXT, EXECUTE_CONTEXT, INSERT_CONTEXT, MODEL_TYPE_DELETE, MODEL_TYPE_EXECUTE, MODEL_TYPE_INSERT, MODEL_TYPE_RETRIEVE, MODEL_TYPE_UPDATE, RETRIEVE_CONTEXT, UPDATE_CONTEXT
 
Fields inherited from interface com.iplanet.jato.view.WebActions
ACTION_CLEAR, ACTION_DELETE, ACTION_EXECUTE, ACTION_FIRST, ACTION_INSERT, ACTION_LAST, ACTION_NEXT, ACTION_PREV, ACTION_PREVIOUS, ACTION_REFRESH, ACTION_SELECT, ACTION_UPDATE
 
Method Summary
 void clearPageSessionAttributes()
          This method clears all page-scoped "session" attributes from this view bean's internal list.
 void forward(java.lang.String target, ViewBean targetViewBean, RequestContext requestContext)
          Deprecated. Beginning in JATO 1.1, the view bean used by a JSP is obtained solely via the ViewBeanManager. Therefore, this method no longer works as advertsied. In fact, the specified view bean instance will only be used if it is the one declared by the JSP. In short, it is no longer possible to dynamically change the view bean used by a JSP at runtime (note that several JSPs can still declare and use the same view bean). For forwarding to a view bean using an alternate JSP, change the default display URL for a target view bean before calling its forwardTo() method.
 void forwardTo(RequestContext requestContext)
          Forwards the request to this view bean, displaying the page.
 java.lang.String getDefaultDisplayURL()
          Returns the default URL of the resource (JSP) used when rendering this view bean.
 java.lang.String getDisplayURL()
          Returns the URL that will be used to display this view bean.
 Model getModel(java.lang.Class modelClass)
          Convenience method to make obtaining a model instance by its default name from the ModelManager easier.
 java.lang.String getModuleURL()
          Returns this ViewBean's module URL.
 java.lang.Object getPageSessionAttribute(java.lang.String name)
          This method gets the value of a page-scoped "session" attribute.
 java.lang.String getPageSessionAttributeString(boolean isEmbedded)
          Returns the serialized page session attributes as a URL encoded string.
 java.lang.String getRequestInvocationName()
          Returns a logical string that is used by the application servlet to dispatch a request to a particular target view bean.
 javax.servlet.http.HttpSession getSession()
          Convenience method to make obtaining the HttpSession instance from the RequestContext easier.
 ViewBean getViewBean(java.lang.Class viewBeanClass)
          Convenience method to make obtaining a view bean instance from the ViewBeanManager easier.
 void include(java.lang.String target, ViewBean targetViewBean, RequestContext requestContext)
          Deprecated. Beginning in JATO 1.1, the view bean used by a JSP is obtained solely via the ViewBeanManager. Therefore, this method no longer works as advertsied. In fact, the specified view bean instance will only be used if it is the one declared by the JSP. In short, it is no longer possible to dynamically change the view bean used by a JSP at runtime (note that several JSPs can still declare and use the same view bean). For including a view bean using an alternate JSP, change the default display URL for a target view bean before calling its forwardTo() method.
 boolean invokeRequestHandler()
          Invokes the request handling mechanism that corresponds to the current request.
 java.lang.Object removePageSessionAttribute(java.lang.String name)
          This method removes a page-scoped "session" attribute from this view bean's ' * internal list of attributes.
 void securityCheck()
          This method is the first method called during the display processing of the JSP, and should be used to enforce any security necessary to the display of this page.
 void setDefaultDisplayURL(java.lang.String url)
          Sets the default URL of the resource (JSP) used when rendering this view bean.
 void setPageSessionAttribute(java.lang.String name, java.io.Serializable value)
          This method sets the value of a page-scoped "session" attribute.
 
Methods inherited from interface com.iplanet.jato.view.ContainerView
beginChildDisplay, beginDisplay, endChildDisplay, endDisplay, getChild, getChildNames, getChildType, getDefaultModel, getDisplayField, getDisplayFieldValue, getNumChildren, mapRequestParameters, resetChildren, setDisplayFieldValue
 
Methods inherited from interface com.iplanet.jato.view.View
getName, getParent, getQualifiedName, setParent
 
Methods inherited from interface com.iplanet.jato.RequestHandler
acceptRequest, getRequestContext, handleRequest
 
Methods inherited from interface com.iplanet.jato.RequestParticipant
setRequestContext
 
Methods inherited from interface com.iplanet.jato.view.WebActionHandler
getWebActionModels, handleWebAction, isAutoRetrieveEnabled, setAutoRetrieveEnabled
 

Field Detail

PAGE_SESSION_ATTRIBUTE_NVP_NAME

public static final java.lang.String PAGE_SESSION_ATTRIBUTE_NVP_NAME
The key used to store page "session" attributes in the HTML page

VIEW_BEAN_NAME_SUFFIX

public static final java.lang.String VIEW_BEAN_NAME_SUFFIX
Method Detail

getModuleURL

public java.lang.String getModuleURL()
Returns this ViewBean's module URL. This URL is normally used in the JSP form tag's action attribute and to generate HREFs in the JSP.

getDisplayURL

public java.lang.String getDisplayURL()
Returns the URL that will be used to display this view bean. This method is used internally to obtain the display URL immediately before display begins; therefore, developers can override this method to perform alternative URL lookups. The default implementation of this method should return the default URL specified by the getDefaultDisplayURL() method.
Returns:
The display URL, relative to the context root. This URL does NOT have to refer to a JSP, but normally should.

getDefaultDisplayURL

public java.lang.String getDefaultDisplayURL()
Returns the default URL of the resource (JSP) used when rendering this view bean. This URL need not be the only URL that uses this view bean, but this URL will be the default preference. Normally, this URL is of this form:
	 /<application>/<module>/<page>.jsp
 
Returns:
The application- and container-dependent URL of the resource (JSP) normally used to render this view bean, relative to the context root. This URL does NOT have to refer to a JSP, but normally should.

setDefaultDisplayURL

public void setDefaultDisplayURL(java.lang.String url)
Sets the default URL of the resource (JSP) used when rendering this view bean. This URL need not be the only URL that uses this view bean, but this URL will be the default preference. Normally, this URL is of this form:
	 /<application>/<module>/<page>.jsp
 
Returns:
The application- and container-dependent URL of the resource (JSP) normally used to render this view bean, relative to the context root. This URL does NOT have to refer to a JSP, but normally should.

getRequestInvocationName

public java.lang.String getRequestInvocationName()
Returns a logical string that is used by the application servlet to dispatch a request to a particular target view bean. This value is automatically encoded in the rendered JSP to route request back to the generated view bean. Developers need not concern themselves with the implementation of this method in the current implementation.
Returns:
The invocation name used to locate this view bean

forwardTo

public void forwardTo(RequestContext requestContext)
               throws NavigationException
Forwards the request to this view bean, displaying the page. This method is equivalent to a call to RequestDispatcher.forward(...). Therefore, any actions taken after this method is called are subject to the actions allowed by the servlet container. Specifically, most servlet containers will not allow sending of additional data to the response output stream after calling forward(...).
Parameters:
requestContext - The current request context object
Throws:
NavigationException - Thrown by the servlet container if there is an error forwarding to the view bean's default URL. This exception will only be thrown if the container throws an IOException or ServletException, and that exception will be available through the NavigationException's getRootCause() method.

forward

public void forward(java.lang.String target,
                    ViewBean targetViewBean,
                    RequestContext requestContext)
             throws NavigationException
Deprecated. Beginning in JATO 1.1, the view bean used by a JSP is obtained solely via the ViewBeanManager. Therefore, this method no longer works as advertsied. In fact, the specified view bean instance will only be used if it is the one declared by the JSP. In short, it is no longer possible to dynamically change the view bean used by a JSP at runtime (note that several JSPs can still declare and use the same view bean). For forwarding to a view bean using an alternate JSP, change the default display URL for a target view bean before calling its forwardTo() method.

Forward the request to the specified view bean and target resource. This method uses the specified resource URL to render the specified view bean. Note that this method does not ensure that the target resource and the view bean are compatible. In terms of the interaction with the servlet container, this method is equivalent to a call to RequestDispatcher.forward(...). Therefore, any actions taken after this method is called are subject to the actions allowed by the servlet container.
Parameters:
target - The target resource (normally a JSP) used to render the specified view ban
targetViewBean - The view bean to be rendered by the target resource. This instance is placed in the request attributes so that is is automatically available to the target JSP via a useBean directive. The name of the request attribute containing the target view bean is specified by the ViewBean.REQUEST_ATTRIBUTE_NAME constant.
requestContext - The current request context object
Throws:
NavigationException - Thrown by the servlet container if there is an error forwarding to the URL resource. This exception will only be thrown if the container throws an IOException or ServletException, and that exception will be available through the NavigationException .getRootCause() method.

include

public void include(java.lang.String target,
                    ViewBean targetViewBean,
                    RequestContext requestContext)
             throws NavigationException
Deprecated. Beginning in JATO 1.1, the view bean used by a JSP is obtained solely via the ViewBeanManager. Therefore, this method no longer works as advertsied. In fact, the specified view bean instance will only be used if it is the one declared by the JSP. In short, it is no longer possible to dynamically change the view bean used by a JSP at runtime (note that several JSPs can still declare and use the same view bean). For including a view bean using an alternate JSP, change the default display URL for a target view bean before calling its forwardTo() method.

Include in the response output the target resource, using the specified view bean. Note that this method does not ensure that the target resource and the view bean are compatible.

In terms of the interaction with the servlet container, this method is equivalent to a call to RequestDispatcher.include(...). Therefore, any actions taken after this method is called are subject to the actions allowed by the servlet container.

Parameters:
target - The target resource (normally a JSP) used to render the specified view ban
targetViewBean - The view bean to be rendered by the target resource. This instance is placed in the request attributes so that is is automatically available to the target JSP via a useBean directive. The name of the request attribute containing the target view bean is specified by the ViewBean.REQUEST_ATTRIBUTE_NAME constant.
requestContext - The current request context object
Throws:
NavigationException - Thrown by the servlet container if there is an error including to the view bean's default URL. This exception will only be thrown if the container throws an IOException or ServletException, and that exception will be available through the NavigationException's getRootCause() method.

invokeRequestHandler

public boolean invokeRequestHandler()
                             throws java.lang.Exception
Invokes the request handling mechanism that corresponds to the current request. The view bean may implement this behavior in any way it sees fit, and the request handling behavior may vary with implementation. For example, the default implementation invokes the handleRequest method on the request-handling view that corresponds to the request. Such a view may be the view bean itself or one of its children.
Throws:
java.io.IOException - Thrown if an exception occurs writing to the response output stream during handling of the request
javax.servlet.ServletException - Thrown if any other exception occurs during handling of the request

securityCheck

public void securityCheck()
                   throws SecurityCheckException
This method is the first method called during the display processing of the JSP, and should be used to enforce any security necessary to the display of this page. If a security violation occurs (as defined by the application), the view bean should throw an instance of SecurityCheckException. This method never throws an exception in the default implementation, meaning there is no security checking enabled by default.

getPageSessionAttribute

public java.lang.Object getPageSessionAttribute(java.lang.String name)
This method gets the value of a page-scoped "session" attribute. Page session attributes are encoded into a rendered page automatically and are repopulated when a page is resubmitted.

The page session API is intended to mirror the standard user session API, but maintain values that are related only to a given page and request. This means that the page session can be used to specify context information that is not subject to confusion if the user presses his browser's Back button or otherwise follows a different path through the application that is different than the server's placement of the user within the application. Note that the use of the term "session" here is for analogy only. Page session objects are never actually stored in the HttpSession.

For example, the page session attributes can be used to specify the current record being displayed on a page. If a user backtracks to a prior page using his browser's Back button and resubmits it, the application can take appropriate action that is based on the record location encoded in the page, rather than the location of the last rendered record.

Page session attributes are automatically repopulated from their serialized form in the page when a page is resubmitted. Page session attributes are not automatically cleared when a page is displayed. Thus, they will automatically persist if a page is submitted and then redisplayed.

Parameters:
name - The name of the page session attribute to retrieve
Returns:
The specified page session attribute, or null if the named attribute doesn't exist.

setPageSessionAttribute

public void setPageSessionAttribute(java.lang.String name,
                                    java.io.Serializable value)
This method sets the value of a page-scoped "session" attribute. Page session attributes are serialized into a rendered page automatically and are repopulated when a page is resubmitted. Page session attribute values are only available to the view bean instance that handles the incoming request of the previously displayed page.

The page session API is intended to mirror the standard user session API, but maintain values that are related only to a given page and request. This means that the page session can be used to specify context information that is not subject to confusion if the user presses his browser's Back button or otherwise follows a different path through the application that is different than the server's placement of the user within the application. Page session objects are never actually stored in the HttpSession.

For example, the page session attributes can be used to specify the current record being displayed on a page. If a user backtracks to a prior page using his browser's Back button and resubmits it, the application can take appropriate action that is based on the record location encoded in the page, rather than the location of the last rendered record. Page session attributes are automatically repopulated from their serialized form in the page when a page is resubmitted. Page session attributes are not automatically cleared when a page is displayed. Thus, they will automatically persist if a page is submitted and then redisplayed.

Parameters:
name - The name of the page session attribute to set
value - The page session attribute value. If this value is null, the page session attribute is removed from the list of attributes and will not be encoded into the next display of this view bean.

removePageSessionAttribute

public java.lang.Object removePageSessionAttribute(java.lang.String name)
This method removes a page-scoped "session" attribute from this view bean's ' * internal list of attributes. The specified attribute will not be encoded into the next display of this view bean.

The page session API is intended to mirror the standard user session API, but maintain values that are related only to a given page and request. This means that the page session can be used to specify context information that is not subject to confusion if the user presses his browser's Back button or otherwise follows a different path through the application that is different than the server's placement of the user within the application. Page session objects are never actually stored in the HttpSession.

For example, the page session attributes can be used to specify the current record being displayed on a page. If a user backtracks to a prior page using his browser's Back button and resubmits it, the application can take appropriate action that is based on the record location encoded in the page, rather than the location of the last rendered record. Page session attributes are automatically repopulated from their serialized form in the page when a page is resubmitted. Page session attributes are not automatically cleared when a page is displayed. Thus, they will automatically persist if a page is submitted and then redisplayed.

Parameters:
name - The name of the page session attribute to remove
return - The page session attribute that was removed, or null if that attribute did not exist.

getPageSessionAttributeString

public java.lang.String getPageSessionAttributeString(boolean isEmbedded)
Returns the serialized page session attributes as a URL encoded string. This method is normally used by the application servlet and HREF display fields when they encode the page session information into the displaying page. This method could also be called by developers wishing to include this information into custom (non-ViewBean-managed) hrefs or forms.

The page session API is intended to mirror the standard user session API, but maintain values that are related only to a given page and request. This means that the page session can be used to specify context information that is not subject to confusion if the user presses his browser's Back button or otherwise follows a different path through the application that is different than the server's placement of the user within the application. Page session objects are never actually stored in the HttpSession.

For example, the page session attributes can be used to specify the current record being displayed on a page. If a user backtracks to a prior page using his browser's Back button and resubmits it, the application can take appropriate action that is based on the record location encoded in the page, rather than the location of the last rendered record. Page session attributes are automatically repopulated from their serialized form in the page when a page is resubmitted. Page session attributes are not automatically cleared when a page is displayed. Thus, they will automatically persist if a page is submitted and then redisplayed.

Parameters:
isEmbedded - If true, this method prefixes the string with a form name-value separator ("&")

clearPageSessionAttributes

public void clearPageSessionAttributes()
This method clears all page-scoped "session" attributes from this view bean's internal list. No attributes will be encoded into the next display of this view bean.

The page session API is intended to mirror the standard user session API, but maintain values that are related only to a given page and request. This means that the page session can be used to specify context information that is not subject to confusion if the user presses his browser's Back button or otherwise follows a different path through the application that is different than the server's placement of the user within the application. Page session objects are never actually stored in the HttpSession.

For example, the page session attributes can be used to specify the current record being displayed on a page. If a user backtracks to a prior page using his browser's Back button and resubmits it, the application can take appropriate action that is based on the record location encoded in the page, rather than the location of the last rendered record. Page session attributes are automatically repopulated from their serialized form in the page when a page is resubmitted. Page session attributes are not automatically cleared when a page is displayed. Thus, they will automatically persist if a page is submitted and then redisplayed.

Parameters:
name - The name of the page session attribute to remove
return - The page session attribute that was removed, or null if that attribute did not exist.

getModel

public Model getModel(java.lang.Class modelClass)
Convenience method to make obtaining a model instance by its default name from the ModelManager easier. It is a replacement for the following:
   getRequestContext().getModelManager().getModel(modelClass)
 

getViewBean

public ViewBean getViewBean(java.lang.Class viewBeanClass)
Convenience method to make obtaining a view bean instance from the ViewBeanManager easier. It is a replacement for the following:
   getRequestContext().getViewBeanManager().getViewBean(viewBeanClass)
 

getSession

public javax.servlet.http.HttpSession getSession()
Convenience method to make obtaining the HttpSession instance from the RequestContext easier. It is a replacement for the following:
   getRequestContext().getRequest().getSession(true)