com.opencms.flex.jsp
Class CmsJspActionElement

java.lang.Object
  |
  +--com.opencms.flex.jsp.CmsJspActionElement

public class CmsJspActionElement
extends java.lang.Object

Bean to be used in JSP scriptlet code that provides direct access to the functionality offered by the opencms taglib.

By instanciating a bean of this type and accessing the methods provided by the instance, all functionality of the OpenCms JSP taglib can be easily used from within JSP scriplet code,

Initialize this bean at the beginning of your JSP like this:

 <jsp:useBean id="cms" class="com.opencms.flex.jsp.CmsJspActionElement">
 <% cms.init(pageContext, request, response); %>
 </jsp:useBean>
 
All exceptions that occur when calling any method of this class are catched and written to the log output only, so that a template still has a chance of working at last in some elements.

Since:
5.0 beta 2
Version:
$Revision: 1.24 $
Author:
Alexander Kandzior (a.kandzior@alkacon.com)

Field Summary
static java.lang.String C_NOT_INITIALIZED
          Error message in case bean was not properly initialized
 
Constructor Summary
CmsJspActionElement()
          Empty constructor, required for every JavaBean.
CmsJspActionElement(javax.servlet.jsp.PageContext context, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res)
          Constructor, with parameters.
 
Method Summary
 com.opencms.file.CmsObject getCmsObject()
          Returns the CmsObject from the wrapped request.
 java.lang.String getContent(java.lang.String target)
          Returns the processed output of an OpenCms resource in a String.
 boolean getHandleExceptions()
          Returns true if Exceptions are handled by the class instace, or false if they will be thrown and have to be handled by the calling class.
 com.opencms.flex.util.CmsMessages getMessages(java.lang.String bundleName, java.lang.String language)
          Generates an initialized instance of CmsMessages for convenient access to localized resource bundles.
 com.opencms.flex.util.CmsMessages getMessages(java.lang.String bundleName, java.lang.String language, java.lang.String defaultLanguage)
          Generates an initialized instance of CmsMessages for convenient access to localized resource bundles.
 com.opencms.flex.util.CmsMessages getMessages(java.lang.String bundleName, java.lang.String language, java.lang.String country, java.lang.String variant, java.lang.String defaultLanguage)
          Generates an initialized instance of CmsMessages for convenient access to localized resource bundles.
 com.opencms.flex.jsp.CmsJspNavBuilder getNavigation()
          Returns an initialized CmsJspNavBuilder instance.
 javax.servlet.jsp.PageContext getPageContext()
          Returns the JSP page context wrapped by this element.
 javax.servlet.http.HttpServletRequest getRequest()
          Returns the request wrapped by the element.
 com.opencms.file.CmsRequestContext getRequestContext()
          Returns the current request context from the internal CmsObject.
 javax.servlet.http.HttpServletResponse getResponse()
          Returns the reponse wrapped by this element.
 void include(java.lang.String target)
          Include a sub-element without paramters from the OpenCms VFS, same as using the <cms:include file="..."
 void include(java.lang.String target, java.lang.String element)
          Include a named sub-element without paramters from the OpenCms VFS, same as using the <cms:include file="..." element="..."
 void include(java.lang.String target, java.lang.String element, java.util.Map parameterMap)
          Include a named sub-element with paramters from the OpenCms VFS, same as using the <cms:include file="..." element="..."
 void includeSilent(java.lang.String target, java.lang.String element)
          Includes a named sub-element supressing all Exceptions that occur during the include, otherwise the same as using include(String, String, Map null).
 void includeSilent(java.lang.String target, java.lang.String element, java.util.Map parameterMap)
          Includes a named sub-element supressing all Exceptions that occur during the include, otherwise the same as using include(String, String, Map).
 java.lang.String info(java.lang.String property)
          Returns an OpenCms or JVM system info property value, same as using the <cms:info property="..."
 void init(javax.servlet.jsp.PageContext context, com.opencms.flex.cache.CmsFlexRequest req, com.opencms.flex.cache.CmsFlexResponse res)
          Initialize the bean with the current page context, request and response.
 void init(javax.servlet.jsp.PageContext context, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res)
          Initialize the bean with the current page context, request and response.
 java.lang.String label(java.lang.String label)
          Returns an OpenCms workplace label.
 java.lang.String link(java.lang.String link)
          Calculate a link with the OpenCms link management, same as using the <cms:link>...
 java.util.Map properties()
          Returns all properites of the current file.
 java.util.Map properties(java.lang.String file)
          Returns all properites of the selected file.
 java.lang.String property(java.lang.String name)
          Returns a selected file property value, same as using the <cms:property name="..."
 java.lang.String property(java.lang.String name, java.lang.String file)
          Returns a selected file property value, same as using the <cms:property name="..." file="..."
 java.lang.String property(java.lang.String name, java.lang.String file, java.lang.String defaultValue)
          Returns a selected file property value, same as using the <cms:property name="..." file="..." default="..."
 java.lang.String property(java.lang.String name, java.lang.String file, java.lang.String defaultValue, boolean escapeHtml)
          Returns a selected file property value with optional HTML escaping, same as using the <cms:property name="..." file="..." default="..."
 void setHandleExceptions(boolean value)
          Controls if Exceptions that occur in methods of this class are supressed (true) or not (false).
 boolean template(java.lang.String element)
          Checks if a template part should be used or not, same as using the <cms:template element="..."
 java.lang.String user(java.lang.String property)
          Returns a selected user property, i.e. information about the currently logged in user, same as using the <cms:user property="..."
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

C_NOT_INITIALIZED

public static final java.lang.String C_NOT_INITIALIZED
Error message in case bean was not properly initialized

See Also:
Constant Field Values
Constructor Detail

CmsJspActionElement

public CmsJspActionElement()
Empty constructor, required for every JavaBean.


CmsJspActionElement

public CmsJspActionElement(javax.servlet.jsp.PageContext context,
                           javax.servlet.http.HttpServletRequest req,
                           javax.servlet.http.HttpServletResponse res)
Constructor, with parameters.

Parameters:
req - the JSP request
res - the JSP response
Method Detail

init

public void init(javax.servlet.jsp.PageContext context,
                 com.opencms.flex.cache.CmsFlexRequest req,
                 com.opencms.flex.cache.CmsFlexResponse res)
Initialize the bean with the current page context, request and response.

It is required to call one of the init() methods before you can use the instance of this bean.

Parameters:
req - the JSP request casted to a CmsFlexRequest
res - the JSP response casted to a CmsFlexResponse

init

public void init(javax.servlet.jsp.PageContext context,
                 javax.servlet.http.HttpServletRequest req,
                 javax.servlet.http.HttpServletResponse res)
Initialize the bean with the current page context, request and response.

It is required to call one of the init() methods before you can use the instance of this bean.

Parameters:
req - the JSP request
res - the JSP response

getHandleExceptions

public boolean getHandleExceptions()
Returns true if Exceptions are handled by the class instace, or false if they will be thrown and have to be handled by the calling class.

The default is true. If set to false Exceptions that occur internally will be wrapped into a RuntimeException and thrown to the calling class instance.

Important: Exceptions that occur during a call to includeSilent(String, String, Map) will NOT be handled.

Returns:
true if Exceptions are handled by the class instace, or false if they will be thrown and have to be handled by the calling class

setHandleExceptions

public void setHandleExceptions(boolean value)
Controls if Exceptions that occur in methods of this class are supressed (true) or not (false).

The default is true. If set to false all Exceptions that occur internally will be wrapped into a RuntimeException and thrown to the calling class instance.

Important: Exceptions that occur during a call to includeSilent(String, String, Map) will NOT be handled.


getRequest

public javax.servlet.http.HttpServletRequest getRequest()
Returns the request wrapped by the element.

Returns:
the request wrapped by the element

getResponse

public javax.servlet.http.HttpServletResponse getResponse()
Returns the reponse wrapped by this element.

Returns:
the reponse wrapped by this element

getPageContext

public javax.servlet.jsp.PageContext getPageContext()
Returns the JSP page context wrapped by this element.

Returns:
the JSP page context wrapped by this element

getCmsObject

public com.opencms.file.CmsObject getCmsObject()
Returns the CmsObject from the wrapped request.

This is a convenience method in case you need access to the CmsObject in your JSP scriplets.

Returns:
the CmsObject from the wrapped request
See Also:
CmsFlexRequest.getCmsObject()

include

public void include(java.lang.String target)
             throws javax.servlet.jsp.JspException
Include a sub-element without paramters from the OpenCms VFS, same as using the <cms:include file="..." /> tag.

Parameters:
target - the target uri of the file in the OpenCms VFS (can be relative or absolute)
Throws:
javax.servlet.jsp.JspException - in case there were problems including the target
See Also:
CmsJspTagInclude

include

public void include(java.lang.String target,
                    java.lang.String element)
             throws javax.servlet.jsp.JspException
Include a named sub-element without paramters from the OpenCms VFS, same as using the <cms:include file="..." element="..." /> tag.

Parameters:
target - the target uri of the file in the OpenCms VFS (can be relative or absolute)
element - the element (template selector) to display from the target
Throws:
javax.servlet.jsp.JspException - in case there were problems including the target
See Also:
CmsJspTagInclude

include

public void include(java.lang.String target,
                    java.lang.String element,
                    java.util.Map parameterMap)
             throws javax.servlet.jsp.JspException
Include a named sub-element with paramters from the OpenCms VFS, same as using the <cms:include file="..." element="..." /> tag with parameters in the tag body.

The parameter map should be a map where the keys are Strings (the parameter names) and the values are of type String[]. However, as a convenience feature, in case you provide just a String for the parameter value, it will automatically be translated to a String[1].

The handling of the element parameter depends on the included file type. Most often it is used as template selector.

Important: Exceptions that occur in the include process are NOT handled even if setHandleExceptions(boolean) was set to true.

Parameters:
target - the target uri of the file in the OpenCms VFS (can be relative or absolute)
element - the element (template selector) to display from the target
parameterMap - a map of the request parameters
Throws:
javax.servlet.jsp.JspException - in case there were problems including the target
See Also:
CmsJspTagInclude

includeSilent

public void includeSilent(java.lang.String target,
                          java.lang.String element)
Includes a named sub-element supressing all Exceptions that occur during the include, otherwise the same as using include(String, String, Map null).

This is a convenience method that allows to include elements on a page without checking if they exist or not. If the target element does not exist, nothing is printed to the JSP output.

Parameters:
target - the target uri of the file in the OpenCms VFS (can be relative or absolute)
element - the element (template selector) to display from the target

includeSilent

public void includeSilent(java.lang.String target,
                          java.lang.String element,
                          java.util.Map parameterMap)
Includes a named sub-element supressing all Exceptions that occur during the include, otherwise the same as using include(String, String, Map).

This is a convenience method that allows to include elements on a page without checking if they exist or not. If the target element does not exist, nothing is printed to the JSP output.

Parameters:
target - the target uri of the file in the OpenCms VFS (can be relative or absolute)
element - the element (template selector) to display from the target
parameterMap - a map of the request parameters

link

public java.lang.String link(java.lang.String link)
Calculate a link with the OpenCms link management, same as using the <cms:link>...</cms:link> tag.

This is important to get the right link for exported resources, e.g. for images in the online project.

Parameters:
link - the uri in the OpenCms to link to
Returns:
the translated link
See Also:
CmsJspTagLink

user

public java.lang.String user(java.lang.String property)
Returns a selected user property, i.e. information about the currently logged in user, same as using the <cms:user property="..." /> tag.

Parameters:
property - the user property to display, please see the tag documentation for valid options
Returns:
the value of the selected user property
See Also:
CmsJspTagUser

property

public java.lang.String property(java.lang.String name)
Returns a selected file property value, same as using the <cms:property name="..." /> tag or calling property(String name, String null, String null, boolean false).

Parameters:
name - the name of the property to look for
Returns:
the value of the property found, or null if the property could not be found
See Also:
property(String, String, String, boolean), CmsJspTagProperty

property

public java.lang.String property(java.lang.String name,
                                 java.lang.String file)
Returns a selected file property value, same as using the <cms:property name="..." file="..." /> tag or calling property(String name, String file, String null, boolean false).

Parameters:
name - the name of the property to look for
file - the file (or folder) to look at for the property
Returns:
the value of the property found, or null if the property could not be found
See Also:
property(String, String, String, boolean), CmsJspTagProperty

property

public java.lang.String property(java.lang.String name,
                                 java.lang.String file,
                                 java.lang.String defaultValue)
Returns a selected file property value, same as using the <cms:property name="..." file="..." default="..." /> tag or calling property(String name, String file, String defaultValue, boolean false).

Parameters:
name - the name of the property to look for
file - the file (or folder) to look at for the property
defaultValue - a default value in case the property was not found
Returns:
the value of the property found, or the value of defaultValue if the property could not be found
See Also:
property(String, String, String, boolean), CmsJspTagProperty

property

public java.lang.String property(java.lang.String name,
                                 java.lang.String file,
                                 java.lang.String defaultValue,
                                 boolean escapeHtml)
Returns a selected file property value with optional HTML escaping, same as using the <cms:property name="..." file="..." default="..." /> tag.

Please see the description of the class CmsJspTagProperty for valid options of the file parameter.

Parameters:
name - the name of the property to look for
file - the file (or folder) to look at for the property
defaultValue - a default value in case the property was not found
escapeHtml - if true, special HTML characters in the return value are escaped with their number representations (e.g. & becomes &#38;)
Returns:
the value of the property found, or the value of defaultValue if the property could not be found
See Also:
CmsJspTagProperty

properties

public java.util.Map properties()
Returns all properites of the current file.

Returns:
Map all properties of the current file

properties

public java.util.Map properties(java.lang.String file)
Returns all properites of the selected file.

Please see the description of the class CmsJspTagProperty for valid options of the file parameter.

Parameters:
file - the file (or folder) to look at for the properties
Returns:
Map all properties of the current file (and optional of the folders containing the file)
See Also:
CmsJspTagProperty

info

public java.lang.String info(java.lang.String property)
Returns an OpenCms or JVM system info property value, same as using the <cms:info property="..." /> tag.

See the description of the class CmsJspTagInfo for a detailed list of available options for the property value.

Parameters:
property - the property to look up
Returns:
String the value of the system property
See Also:
CmsJspTagInfo

label

public java.lang.String label(java.lang.String label)
Returns an OpenCms workplace label.

You should consider using a standard java.util.ResourceBundle instead of the OpenCms workplace language files.

Parameters:
label - the label to look up
Returns:
label the value of the label
See Also:
CmsJspTagLabel

template

public boolean template(java.lang.String element)
Checks if a template part should be used or not, same as using the <cms:template element="..." /> tag.

Returns:
true if the element is active, false otherwise
See Also:
CmsJspTagUser

getRequestContext

public com.opencms.file.CmsRequestContext getRequestContext()
Returns the current request context from the internal CmsObject.

Returns:
the current request context from the internal CmsObject

getNavigation

public com.opencms.flex.jsp.CmsJspNavBuilder getNavigation()
Returns an initialized CmsJspNavBuilder instance.

Returns:
CmsJspNavBuilder an initialized CmsJspNavBuilder
See Also:
CmsJspNavBuilder

getMessages

public com.opencms.flex.util.CmsMessages getMessages(java.lang.String bundleName,
                                                     java.lang.String language)
Generates an initialized instance of CmsMessages for convenient access to localized resource bundles.

Parameters:
bundleName - the name of the ResourceBundle to use
language - language indentificator for the locale of the bundle
Returns:
CmsMessages a message bundle initialized with the provided values

getMessages

public com.opencms.flex.util.CmsMessages getMessages(java.lang.String bundleName,
                                                     java.lang.String language,
                                                     java.lang.String defaultLanguage)
Generates an initialized instance of CmsMessages for convenient access to localized resource bundles.

Parameters:
bundleName - the name of the ResourceBundle to use
language - language indentificator for the locale of the bundle
defaultLanguage - default for the language, will be used if language is null or empty String "", and defaultLanguage is not null
Returns:
CmsMessages a message bundle initialized with the provided values

getMessages

public com.opencms.flex.util.CmsMessages getMessages(java.lang.String bundleName,
                                                     java.lang.String language,
                                                     java.lang.String country,
                                                     java.lang.String variant,
                                                     java.lang.String defaultLanguage)
Generates an initialized instance of CmsMessages for convenient access to localized resource bundles.

Parameters:
bundleName - the name of the ResourceBundle to use
language - language indentificator for the locale of the bundle
country - 2 letter country code for the locale of the bundle
variant - a vendor or browser-specific variant code
defaultLanguage - default for the language, will be used if language is null or empty String "", and defaultLanguage is not null
Returns:
CmsMessages a message bundle initialized with the provided values
See Also:
ResourceBundle, CmsMessages

getContent

public java.lang.String getContent(java.lang.String target)
Returns the processed output of an OpenCms resource in a String.

Parameters:
target - the target to process
Returns:
the processed output of an OpenCms resource in a String