org.apache.struts.taglib
Class TagUtils

java.lang.Object
  extended by org.apache.struts.taglib.TagUtils

public class TagUtils
extends Object

Provides helper methods for JSP tags.

Since:
Struts 1.2
Version:
$Rev: 471754 $

Constructor Summary
protected TagUtils()
          Constructor for TagUtils.
 
Method Summary
 Map computeParameters(PageContext pageContext, String paramId, String paramName, String paramProperty, String paramScope, String name, String property, String scope, boolean transaction)
          Compute a set of query parameters that will be dynamically added to a generated URL.
 String computeURL(PageContext pageContext, String forward, String href, String page, String action, String module, Map params, String anchor, boolean redirect)
           
 String computeURL(PageContext pageContext, String forward, String href, String page, String action, String module, Map params, String anchor, boolean redirect, boolean encodeSeparator)
           
 String computeURLWithCharEncoding(PageContext pageContext, String forward, String href, String page, String action, String module, Map params, String anchor, boolean redirect, boolean useLocalEncoding)
          Compute a hyperlink URL based on the forward, href, action or page parameter that is not null.
 String computeURLWithCharEncoding(PageContext pageContext, String forward, String href, String page, String action, String module, Map params, String anchor, boolean redirect, boolean encodeSeparator, boolean useLocalEncoding)
          Compute a hyperlink URL based on the forward, href, action or page parameter that is not null.
 String encodeURL(String url)
          URLencodes a string assuming the character encoding is UTF-8.
 String encodeURL(String url, String enc)
          Use the new URLEncoder.encode() method from Java 1.4 if available, else use the old deprecated version.
 String filter(String value)
          Filter the specified string for characters that are senstive to HTML interpreters, returning the string with these characters replaced by the corresponding character entities.
 String getActionMappingName(String action)
          Return the form action converted into an action mapping path.
 String getActionMappingURL(String action, PageContext pageContext)
          Return the form action converted into a server-relative URL.
 String getActionMappingURL(String action, String module, PageContext pageContext, boolean contextRelative)
          Return the form action converted into a server-relative URL.
 org.apache.struts.action.ActionMessages getActionMessages(PageContext pageContext, String paramName)
          Retrieves the value from request scope and if it isn't already an ActionMessages, some classes are converted to one.
static TagUtils getInstance()
          Returns the Singleton instance of TagUtils.
 org.apache.struts.config.ModuleConfig getModuleConfig(PageContext pageContext)
          Return the default ModuleConfig object if it exists, null if otherwise.
 org.apache.struts.config.ModuleConfig getModuleConfig(String module, PageContext pageContext)
          Return the specified ModuleConfig object for the given prefix if it exists, otherwise a NullPointerException will be thrown.
 int getScope(String scopeName)
          Converts the scope name into its corresponding PageContext constant value.
 Locale getUserLocale(PageContext pageContext, String locale)
          Look up and return current user locale, based on the specified parameters.
 boolean isXhtml(PageContext pageContext)
          Returns true if the custom tags are in XHTML mode.
 Object lookup(PageContext pageContext, String name, String scopeName)
          Locate and return the specified bean, from an optionally specified scope, in the specified page context.
 Object lookup(PageContext pageContext, String name, String property, String scope)
          Locate and return the specified property of the specified bean, from an optionally specified scope, in the specified page context.
 String message(PageContext pageContext, String bundle, String locale, String key)
          Look up and return a message string, based on the specified parameters.
 String message(PageContext pageContext, String bundle, String locale, String key, Object[] args)
          Look up and return a message string, based on the specified parameters.
 String pageURL(HttpServletRequest request, String page, org.apache.struts.config.ModuleConfig moduleConfig)
          Return the context-relative URL that corresponds to the specified page attribute value, calculated based on the pagePattern property of the current module's ModuleConfig.
 boolean present(PageContext pageContext, String bundle, String locale, String key)
          Return true if a message string for the specified message key is present for the specified Locale and bundle.
 org.apache.struts.util.MessageResources retrieveMessageResources(PageContext pageContext, String bundle, boolean checkPageScope)
          Returns the appropriate MessageResources object for the current module and the given bundle.
 void saveException(PageContext pageContext, Throwable exception)
          Save the specified exception as a request attribute for later use.
static void setInstance(TagUtils instance)
          Set the instance.
 void write(PageContext pageContext, String text)
          Write the specified text as the response to the writer associated with this page.
 void writePrevious(PageContext pageContext, String text)
          Write the specified text as the response to the writer associated with the body content for the tag within which we are currently nested.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

TagUtils

protected TagUtils()
Constructor for TagUtils.

Method Detail

getInstance

public static TagUtils getInstance()
Returns the Singleton instance of TagUtils.


setInstance

public static void setInstance(TagUtils instance)
Set the instance. This blatently violates the Singleton pattern, but then some say Singletons are an anti-pattern.

Parameters:
instance - The instance to set.
Since:
1.3.5 Changed to non-final and added setInstance() so TagUtils may be overridden, use at your own risk (you've been warned!!)

computeParameters

public Map computeParameters(PageContext pageContext,
                             String paramId,
                             String paramName,
                             String paramProperty,
                             String paramScope,
                             String name,
                             String property,
                             String scope,
                             boolean transaction)
                      throws JspException
Compute a set of query parameters that will be dynamically added to a generated URL. The returned Map is keyed by parameter name, and the values are either null (no value specified), a String (single value specified), or a String[] array (multiple values specified). Parameter names correspond to the corresponding attributes of the <html:link> tag. If no query parameters are identified, return null.

Parameters:
pageContext - PageContext we are operating in
paramId - Single-value request parameter name (if any)
paramName - Bean containing single-value parameter value
paramProperty - Property (of bean named by paramName containing single-value parameter value
paramScope - Scope containing bean named by paramName
name - Bean containing multi-value parameters Map (if any)
property - Property (of bean named by name containing multi-value parameters Map
scope - Scope containing bean named by name
transaction - Should we add our transaction control token?
Returns:
Map of query parameters
Throws:
JspException - if we cannot look up the required beans
JspException - if a class cast exception occurs on a looked-up bean or property

computeURL

public String computeURL(PageContext pageContext,
                         String forward,
                         String href,
                         String page,
                         String action,
                         String module,
                         Map params,
                         String anchor,
                         boolean redirect)
                  throws MalformedURLException
Throws:
MalformedURLException

computeURLWithCharEncoding

public String computeURLWithCharEncoding(PageContext pageContext,
                                         String forward,
                                         String href,
                                         String page,
                                         String action,
                                         String module,
                                         Map params,
                                         String anchor,
                                         boolean redirect,
                                         boolean useLocalEncoding)
                                  throws MalformedURLException
Compute a hyperlink URL based on the forward, href, action or page parameter that is not null. The returned URL will have already been passed to response.encodeURL() for adding a session identifier.

Parameters:
pageContext - PageContext for the tag making this call
forward - Logical forward name for which to look up the context-relative URI (if specified)
href - URL to be utilized unmodified (if specified)
page - Module-relative page for which a URL should be created (if specified)
action - Logical action name for which to look up the context-relative URI (if specified)
params - Map of parameters to be dynamically included (if any)
anchor - Anchor to be dynamically included (if any)
redirect - Is this URL for a response.sendRedirect()?
Returns:
URL with session identifier
Throws:
MalformedURLException - if a URL cannot be created for the specified parameters

computeURL

public String computeURL(PageContext pageContext,
                         String forward,
                         String href,
                         String page,
                         String action,
                         String module,
                         Map params,
                         String anchor,
                         boolean redirect,
                         boolean encodeSeparator)
                  throws MalformedURLException
Throws:
MalformedURLException

computeURLWithCharEncoding

public String computeURLWithCharEncoding(PageContext pageContext,
                                         String forward,
                                         String href,
                                         String page,
                                         String action,
                                         String module,
                                         Map params,
                                         String anchor,
                                         boolean redirect,
                                         boolean encodeSeparator,
                                         boolean useLocalEncoding)
                                  throws MalformedURLException
Compute a hyperlink URL based on the forward, href, action or page parameter that is not null. The returned URL will have already been passed to response.encodeURL() for adding a session identifier.

Parameters:
pageContext - PageContext for the tag making this call
forward - Logical forward name for which to look up the context-relative URI (if specified)
href - URL to be utilized unmodified (if specified)
page - Module-relative page for which a URL should be created (if specified)
action - Logical action name for which to look up the context-relative URI (if specified)
params - Map of parameters to be dynamically included (if any)
anchor - Anchor to be dynamically included (if any)
redirect - Is this URL for a response.sendRedirect()?
encodeSeparator - This is only checked if redirect is set to false (never encoded for a redirect). If true, query string parameter separators are encoded as >amp;, else & is used.
useLocalEncoding - If set to true, urlencoding is done on the bytes of character encoding from ServletResponse#getCharacterEncoding. Use UTF-8 otherwise.
Returns:
URL with session identifier
Throws:
MalformedURLException - if a URL cannot be created for the specified parameters

encodeURL

public String encodeURL(String url)
URLencodes a string assuming the character encoding is UTF-8.

Parameters:
url -
Returns:
String The encoded url in UTF-8

encodeURL

public String encodeURL(String url,
                        String enc)
Use the new URLEncoder.encode() method from Java 1.4 if available, else use the old deprecated version. This method uses reflection to find the appropriate method; if the reflection operations throw exceptions, this will return the url encoded with the old URLEncoder.encode() method.

Parameters:
enc - The character encoding the urlencode is performed on.
Returns:
String The encoded url.

filter

public String filter(String value)
Filter the specified string for characters that are senstive to HTML interpreters, returning the string with these characters replaced by the corresponding character entities.

Parameters:
value - The string to be filtered and returned

getActionMappingName

public String getActionMappingName(String action)
Return the form action converted into an action mapping path. The value of the action property is manipulated as follows in computing the name of the requested mapping:


getActionMappingURL

public String getActionMappingURL(String action,
                                  PageContext pageContext)
Return the form action converted into a server-relative URL.


getActionMappingURL

public String getActionMappingURL(String action,
                                  String module,
                                  PageContext pageContext,
                                  boolean contextRelative)
Return the form action converted into a server-relative URL.


getActionMessages

public org.apache.struts.action.ActionMessages getActionMessages(PageContext pageContext,
                                                                 String paramName)
                                                          throws JspException
Retrieves the value from request scope and if it isn't already an ActionMessages, some classes are converted to one.

Parameters:
pageContext - The PageContext for the current page
paramName - Key for parameter value
Returns:
ActionErrors in page context.
Throws:
JspException

getModuleConfig

public org.apache.struts.config.ModuleConfig getModuleConfig(PageContext pageContext)
Return the default ModuleConfig object if it exists, null if otherwise.

Parameters:
pageContext - The page context.
Returns:
the ModuleConfig object

getModuleConfig

public org.apache.struts.config.ModuleConfig getModuleConfig(String module,
                                                             PageContext pageContext)
Return the specified ModuleConfig object for the given prefix if it exists, otherwise a NullPointerException will be thrown.

Parameters:
module - The module prefix
pageContext - The page context.
Returns:
the ModuleConfig object
Throws:
NullPointerException - Thrown when module cannot be found

getScope

public int getScope(String scopeName)
             throws JspException
Converts the scope name into its corresponding PageContext constant value.

Parameters:
scopeName - Can be "page", "request", "session", or "application" in any case.
Returns:
The constant representing the scope (ie. PageContext.REQUEST_SCOPE).
Throws:
JspException - if the scopeName is not a valid name.

getUserLocale

public Locale getUserLocale(PageContext pageContext,
                            String locale)
Look up and return current user locale, based on the specified parameters.

Parameters:
pageContext - The PageContext associated with this request
locale - Name of the session attribute for our user's Locale. If this is null, the default locale key is used for the lookup.
Returns:
current user locale

isXhtml

public boolean isXhtml(PageContext pageContext)
Returns true if the custom tags are in XHTML mode.


lookup

public Object lookup(PageContext pageContext,
                     String name,
                     String scopeName)
              throws JspException
Locate and return the specified bean, from an optionally specified scope, in the specified page context. If no such bean is found, return null instead. If an exception is thrown, it will have already been saved via a call to saveException().

Parameters:
pageContext - Page context to be searched
name - Name of the bean to be retrieved
scopeName - Scope to be searched (page, request, session, application) or null to use findAttribute() instead
Returns:
JavaBean in the specified page context
Throws:
JspException - if an invalid scope name is requested

lookup

public Object lookup(PageContext pageContext,
                     String name,
                     String property,
                     String scope)
              throws JspException
Locate and return the specified property of the specified bean, from an optionally specified scope, in the specified page context. If an exception is thrown, it will have already been saved via a call to saveException().

Parameters:
pageContext - Page context to be searched
name - Name of the bean to be retrieved
property - Name of the property to be retrieved, or null to retrieve the bean itself
scope - Scope to be searched (page, request, session, application) or null to use findAttribute() instead
Returns:
property of specified JavaBean
Throws:
JspException - if an invalid scope name is requested
JspException - if the specified bean is not found
JspException - if accessing this property causes an IllegalAccessException, IllegalArgumentException, InvocationTargetException, or NoSuchMethodException

message

public String message(PageContext pageContext,
                      String bundle,
                      String locale,
                      String key)
               throws JspException
Look up and return a message string, based on the specified parameters.

Parameters:
pageContext - The PageContext associated with this request
bundle - Name of the servlet context attribute for our message resources bundle
locale - Name of the session attribute for our user's Locale
key - Message key to be looked up and returned
Returns:
message string
Throws:
JspException - if a lookup error occurs (will have been saved in the request already)

message

public String message(PageContext pageContext,
                      String bundle,
                      String locale,
                      String key,
                      Object[] args)
               throws JspException
Look up and return a message string, based on the specified parameters.

Parameters:
pageContext - The PageContext associated with this request
bundle - Name of the servlet context attribute for our message resources bundle
locale - Name of the session attribute for our user's Locale
key - Message key to be looked up and returned
args - Replacement parameters for this message
Returns:
message string
Throws:
JspException - if a lookup error occurs (will have been saved in the request already)

pageURL

public String pageURL(HttpServletRequest request,
                      String page,
                      org.apache.struts.config.ModuleConfig moduleConfig)

Return the context-relative URL that corresponds to the specified page attribute value, calculated based on the pagePattern property of the current module's ModuleConfig.

Parameters:
request - The servlet request we are processing
page - The module-relative URL to be substituted in to the pagePattern pattern for the current module (MUST start with a slash)
Returns:
context-relative URL

present

public boolean present(PageContext pageContext,
                       String bundle,
                       String locale,
                       String key)
                throws JspException
Return true if a message string for the specified message key is present for the specified Locale and bundle.

Parameters:
pageContext - The PageContext associated with this request
bundle - Name of the servlet context attribute for our message resources bundle
locale - Name of the session attribute for our user's Locale
key - Message key to be looked up and returned
Returns:
true if a message string for message key exists
Throws:
JspException - if a lookup error occurs (will have been saved in the request already)

retrieveMessageResources

public org.apache.struts.util.MessageResources retrieveMessageResources(PageContext pageContext,
                                                                        String bundle,
                                                                        boolean checkPageScope)
                                                                 throws JspException
Returns the appropriate MessageResources object for the current module and the given bundle.

Parameters:
pageContext - Search the context's scopes for the resources.
bundle - The bundle name to look for. If this is null, the default bundle name is used.
checkPageScope - Whether to check page scope
Returns:
MessageResources The bundle's resources stored in some scope.
Throws:
JspException - if the MessageResources object could not be found.

saveException

public void saveException(PageContext pageContext,
                          Throwable exception)
Save the specified exception as a request attribute for later use.

Parameters:
pageContext - The PageContext for the current page
exception - The exception to be saved

write

public void write(PageContext pageContext,
                  String text)
           throws JspException
Write the specified text as the response to the writer associated with this page. WARNING - If you are writing body content from the doAfterBody() method of a custom tag class that implements BodyTag, you should be calling writePrevious() instead.

Parameters:
pageContext - The PageContext object for this page
text - The text to be written
Throws:
JspException - if an input/output error occurs (already saved)

writePrevious

public void writePrevious(PageContext pageContext,
                          String text)
                   throws JspException
Write the specified text as the response to the writer associated with the body content for the tag within which we are currently nested.

Parameters:
pageContext - The PageContext object for this page
text - The text to be written
Throws:
JspException - if an input/output error occurs (already saved)


Copyright © 2000-2008 Apache Software Foundation. All Rights Reserved.