org.opencms.loader
Class CmsJspLoader

java.lang.Object
  extended byorg.opencms.loader.CmsJspLoader
All Implemented Interfaces:
I_CmsConfigurationParameterHandler, I_CmsFlexCacheEnabledLoader, I_CmsResourceLoader

public class CmsJspLoader
extends java.lang.Object
implements I_CmsResourceLoader, I_CmsFlexCacheEnabledLoader

The JSP loader which enables the execution of JSP in OpenCms.

Parameters supported by this loader:

jsp.repository
(Optional) This is the root directory in the "real" file system where generated JSPs are stored. The default is the web application path, e.g. in Tomcat if your web application is names "opencms" it would be ${TOMCAT_HOME}/webapps/opencms/. The jsp.folder (see below) is added to this path. Usually the jsp.repository is not changed.
jsp.folder
(Optional) A path relative to the jsp.repository path where the JSPs generated by OpenCms are stored. The default is to store the generated JSP in /WEB-INF/jsp/. This works well in Tomcat 4, and the JSPs are not accessible directly from the outside this way, only through the OpenCms servlet. Please note: Some servlet environments (e.g. BEA Weblogic) do not permit JSPs to be stored under /WEB-INF. For environments like these, set the path to some place where JSPs can be accessed, e.g. /jsp/ only.
jsp.errorpage.committed
(Optional) This parameter controls behaviour of JSP error pages i.e. <% page errorPage="..." %>. If you find that these don't work in your servlet environment, you should try to change the value here. The default true has been tested with Tomcat 4.1 and 5.0. Older versions of Tomcat like 4.0 require a setting of false.

Since:
6.0.0
Version:
$Revision: 1.112 $
Author:
Alexander Kandzior
See Also:
I_CmsResourceLoader

Field Summary
static java.lang.String CACHE_PROPERTY_BYPASS
          Property value for "cache" that indicates that the FlexCache should be bypassed.
static java.lang.String CACHE_PROPERTY_STREAM
          Property value for "cache" that indicates that the output should be streamed.
static java.lang.String DEFAULT_JSP_FOLDER
          Default jsp folder constant.
static java.lang.String DIRECTIVE_END
          Special JSP directive tag start (%>).
static java.lang.String DIRECTIVE_START
          Special JSP directive tag start (<%().
static java.lang.String JSP_EXTENSION
          Extension for JSP managed by OpenCms (.jsp).
static java.lang.String PARAM_CLIENT_CACHE_MAXAGE
          Cache max age parameter name.
static java.lang.String PARAM_JSP_ERRORPAGE_COMMITTED
          Error page committed parameter name.
static java.lang.String PARAM_JSP_FOLDER
          Jsp folder parameter name.
static java.lang.String PARAM_JSP_REPOSITORY
          Jsp repository parameter name.
static int RESOURCE_LOADER_ID
          The id of this loader.
 
Fields inherited from interface org.opencms.loader.I_CmsResourceLoader
PARAMETER_ELEMENT
 
Fields inherited from interface org.opencms.configuration.I_CmsConfigurationParameterHandler
ADD_PARAMETER_METHOD, INIT_CONFIGURATION_METHOD
 
Constructor Summary
CmsJspLoader()
          The constructor of the class is empty, the initial instance will be created by the resource manager upon startup of OpenCms.
 
Method Summary
 void addConfigurationParameter(java.lang.String paramName, java.lang.String paramValue)
          Adds a configuration parameter to this parameter configurable class instance.
 void destroy()
          Destroy this ResourceLoder, this is a NOOP so far.
 byte[] dump(CmsObject cms, CmsResource file, java.lang.String element, java.util.Locale locale, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res)
          Dumps the processed content of the the requested file (and it's sub-elements) to a byte array.
 byte[] export(CmsObject cms, CmsResource resource, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res)
          Static exports the contents of the requested file and it's sub-elements.
 java.util.Map getConfiguration()
          Returns the configuration of this parameter configurable class instance, or null if the class does not need to be configured.
static java.lang.String getJspRepository()
          Returns the absolute path in the "real" file system for the JSP repository toplevel directory.
 int getLoaderId()
          Returns the id of the ResourceLoader.
 java.lang.String getResourceLoaderInfo()
          Return a String describing the ResourceLoader, which is (localized to the system default locale) "The OpenCms default resource loader for JSP".
 void initConfiguration()
          Initializes a configuration after all parameters have been added.
 boolean isStaticExportEnabled()
          Signals if the loader implementation supports static export of resources.
 boolean isStaticExportProcessable()
          Signals if the loader implementation requires processing during static export of resources.
 boolean isUsableForTemplates()
          Signals if the loader implementation is usable for creating templates.
 boolean isUsingUriWhenLoadingTemplate()
          Signals if a loader that supports templates must be invoked on the template URI or the resource URI.
 void load(CmsObject cms, CmsResource file, javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res)
          Basic top-page processing method for a I_CmsResourceLoader, this method is called if the page is called as a sub-element on a page not already loded with a I_CmsResourceLoader.
 void service(CmsObject cms, CmsResource resource, javax.servlet.ServletRequest req, javax.servlet.ServletResponse res)
          Does the job of including the requested resource, this method is called directly if the element is called as a sub-element from another I_CmsResourceLoader.
 void setFlexCache(CmsFlexCache cache)
          Will be called after the resource manager was initialized.
static java.lang.String updateJsp(CmsResource resource, CmsFlexController controller, java.util.Set updatedFiles)
          Updates a JSP page in the "real" file system in case the VFS resource has changed.
static void updateJspFromRequest(java.lang.String servletPath, CmsFlexRequest request)
          Updates the internal jsp repository when the servlet container tries to compile a jsp file that may not exist.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CACHE_PROPERTY_BYPASS

public static final java.lang.String CACHE_PROPERTY_BYPASS
Property value for "cache" that indicates that the FlexCache should be bypassed.

See Also:
Constant Field Values

CACHE_PROPERTY_STREAM

public static final java.lang.String CACHE_PROPERTY_STREAM
Property value for "cache" that indicates that the output should be streamed.

See Also:
Constant Field Values

DEFAULT_JSP_FOLDER

public static final java.lang.String DEFAULT_JSP_FOLDER
Default jsp folder constant.

See Also:
Constant Field Values

DIRECTIVE_END

public static final java.lang.String DIRECTIVE_END
Special JSP directive tag start (%>).

See Also:
Constant Field Values

DIRECTIVE_START

public static final java.lang.String DIRECTIVE_START
Special JSP directive tag start (<%().

See Also:
Constant Field Values

JSP_EXTENSION

public static final java.lang.String JSP_EXTENSION
Extension for JSP managed by OpenCms (.jsp).

See Also:
Constant Field Values

PARAM_CLIENT_CACHE_MAXAGE

public static final java.lang.String PARAM_CLIENT_CACHE_MAXAGE
Cache max age parameter name.

See Also:
Constant Field Values

PARAM_JSP_ERRORPAGE_COMMITTED

public static final java.lang.String PARAM_JSP_ERRORPAGE_COMMITTED
Error page committed parameter name.

See Also:
Constant Field Values

PARAM_JSP_FOLDER

public static final java.lang.String PARAM_JSP_FOLDER
Jsp folder parameter name.

See Also:
Constant Field Values

PARAM_JSP_REPOSITORY

public static final java.lang.String PARAM_JSP_REPOSITORY
Jsp repository parameter name.

See Also:
Constant Field Values

RESOURCE_LOADER_ID

public static final int RESOURCE_LOADER_ID
The id of this loader.

See Also:
Constant Field Values
Constructor Detail

CmsJspLoader

public CmsJspLoader()
The constructor of the class is empty, the initial instance will be created by the resource manager upon startup of OpenCms.

See Also:
CmsResourceManager
Method Detail

getJspRepository

public static java.lang.String getJspRepository()
Returns the absolute path in the "real" file system for the JSP repository toplevel directory.

Returns:
The full path to the JSP repository

updateJsp

public static java.lang.String updateJsp(CmsResource resource,
                                         CmsFlexController controller,
                                         java.util.Set updatedFiles)
                                  throws java.io.IOException,
                                         javax.servlet.ServletException,
                                         CmsLoaderException
Updates a JSP page in the "real" file system in case the VFS resource has changed.

Also processes the <%@ cms %> tags before the JSP is written to the real FS. Also recursively updates all files that are referenced by a <%@ cms %> tag on this page to make sure the file actually exists in the real FS. All <%@ include %> tags are parsed and the name in the tag is translated from the OpenCms VFS path to the path in the real FS. The same is done for filenames in <%@ page errorPage=... %> tags.

Parameters:
resource - the requested JSP file resource in the VFS
controller - the controller for the JSP integration
updatedFiles - a Set containing all JSP pages that have been already updated
Returns:
the file name of the updated JSP in the "real" FS
Throws:
javax.servlet.ServletException - might be thrown in the process of including the JSP
java.io.IOException - might be thrown in the process of including the JSP
CmsLoaderException - if the resource type can not be read

updateJspFromRequest

public static void updateJspFromRequest(java.lang.String servletPath,
                                        CmsFlexRequest request)
Updates the internal jsp repository when the servlet container tries to compile a jsp file that may not exist.

Parameters:
servletPath - the servlet path, just to avoid unneeded recursive calls
request - the current request

addConfigurationParameter

public void addConfigurationParameter(java.lang.String paramName,
                                      java.lang.String paramValue)
Description copied from interface: I_CmsConfigurationParameterHandler
Adds a configuration parameter to this parameter configurable class instance.

Specified by:
addConfigurationParameter in interface I_CmsConfigurationParameterHandler
Parameters:
paramName - the name of the parameter
paramValue - the value for the parameter
See Also:
I_CmsConfigurationParameterHandler.addConfigurationParameter(java.lang.String, java.lang.String)

destroy

public void destroy()
Destroy this ResourceLoder, this is a NOOP so far.

Specified by:
destroy in interface I_CmsResourceLoader

dump

public byte[] dump(CmsObject cms,
                   CmsResource file,
                   java.lang.String element,
                   java.util.Locale locale,
                   javax.servlet.http.HttpServletRequest req,
                   javax.servlet.http.HttpServletResponse res)
            throws javax.servlet.ServletException,
                   java.io.IOException
Description copied from interface: I_CmsResourceLoader
Dumps the processed content of the the requested file (and it's sub-elements) to a byte array.

Dumping the content is like calling "load" where the result is not written to the response stream, but to the returned byte array. Dumping is different from an export because the export might actually require that the content is handled or modified in a special way, or set special http headers.

Moreover, if the page type is template based, calling "dump" will not trigger the template but directly deliver the contents from the selected element.

Specified by:
dump in interface I_CmsResourceLoader
Parameters:
cms - used to access the OpenCms VFS
file - the requested resource in the VFS
element - the element in the file to display
locale - the locale to display
req - the servlet request
res - the servlet response
Returns:
the content of the processed file
Throws:
java.io.IOException - might be thrown by the servlet environment
javax.servlet.ServletException - might be thrown by the servlet environment
See Also:
I_CmsResourceLoader.dump(org.opencms.file.CmsObject, org.opencms.file.CmsResource, java.lang.String, java.util.Locale, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

export

public byte[] export(CmsObject cms,
                     CmsResource resource,
                     javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse res)
              throws javax.servlet.ServletException,
                     java.io.IOException
Description copied from interface: I_CmsResourceLoader
Static exports the contents of the requested file and it's sub-elements.

During static export, the resource content may be written to 2 streams: The export stream, and the http response output stream. Which stream is actually used depends wether the export is in "on demand" or "after publish" mode. In "on demand" mode, the resource needs to be written both to the response stream and to the file stream. In "after publish" mode, it's usually only written to the file stream, but sometimes it's required to write to the response stream as well.

Specified by:
export in interface I_CmsResourceLoader
Parameters:
cms - the initialized CmsObject which provides user permissions
resource - the requested OpenCms VFS resource
req - the servlet request
res - the servlet response
Returns:
the contents to export, or null if no export is required
Throws:
javax.servlet.ServletException - might be thrown in the process of including the sub element
java.io.IOException - might be thrown in the process of including the sub element
See Also:
I_CmsResourceLoader.export(org.opencms.file.CmsObject, org.opencms.file.CmsResource, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

getConfiguration

public java.util.Map getConfiguration()
Description copied from interface: I_CmsConfigurationParameterHandler
Returns the configuration of this parameter configurable class instance, or null if the class does not need to be configured.

All elements in the configuration are key, value String pairs, set using the I_CmsConfigurationParameterHandler.addConfigurationParameter(String, String) method during initialization of the loader.

Implementations will (should) not to return a direct reference to the internal configuration but just a copy of it, to avoid unwanted external manipulation.

Specified by:
getConfiguration in interface I_CmsConfigurationParameterHandler
Returns:
the configuration of this resource loader, or null
See Also:
I_CmsConfigurationParameterHandler.getConfiguration()

getLoaderId

public int getLoaderId()
Description copied from interface: I_CmsResourceLoader
Returns the id of the ResourceLoader.

Specified by:
getLoaderId in interface I_CmsResourceLoader
Returns:
the id of the ResourceLoader
See Also:
I_CmsResourceLoader.getLoaderId()

getResourceLoaderInfo

public java.lang.String getResourceLoaderInfo()
Return a String describing the ResourceLoader, which is (localized to the system default locale) "The OpenCms default resource loader for JSP".

Specified by:
getResourceLoaderInfo in interface I_CmsResourceLoader
Returns:
a describing String for the ResourceLoader

initConfiguration

public void initConfiguration()
Description copied from interface: I_CmsConfigurationParameterHandler
Initializes a configuration after all parameters have been added.

Specified by:
initConfiguration in interface I_CmsConfigurationParameterHandler
See Also:
I_CmsConfigurationParameterHandler.initConfiguration()

isStaticExportEnabled

public boolean isStaticExportEnabled()
Description copied from interface: I_CmsResourceLoader
Signals if the loader implementation supports static export of resources.

Specified by:
isStaticExportEnabled in interface I_CmsResourceLoader
Returns:
true if static export is supported, false otherwise
See Also:
I_CmsResourceLoader.isStaticExportEnabled()

isStaticExportProcessable

public boolean isStaticExportProcessable()
Description copied from interface: I_CmsResourceLoader
Signals if the loader implementation requires processing during static export of resources.

Specified by:
isStaticExportProcessable in interface I_CmsResourceLoader
Returns:
true if static export processing is required, false otherwise
See Also:
I_CmsResourceLoader.isStaticExportProcessable()

isUsableForTemplates

public boolean isUsableForTemplates()
Description copied from interface: I_CmsResourceLoader
Signals if the loader implementation is usable for creating templates.

Specified by:
isUsableForTemplates in interface I_CmsResourceLoader
Returns:
true if the loader implementation is usable for creating templates, false otherwise
See Also:
I_CmsResourceLoader.isUsableForTemplates()

isUsingUriWhenLoadingTemplate

public boolean isUsingUriWhenLoadingTemplate()
Description copied from interface: I_CmsResourceLoader
Signals if a loader that supports templates must be invoked on the template URI or the resource URI.

Specified by:
isUsingUriWhenLoadingTemplate in interface I_CmsResourceLoader
Returns:
true if the resource URI is to be used, false if the template URI is to be used
See Also:
I_CmsResourceLoader.isUsingUriWhenLoadingTemplate()

load

public void load(CmsObject cms,
                 CmsResource file,
                 javax.servlet.http.HttpServletRequest req,
                 javax.servlet.http.HttpServletResponse res)
          throws javax.servlet.ServletException,
                 java.io.IOException,
                 CmsException
Description copied from interface: I_CmsResourceLoader
Basic top-page processing method for a I_CmsResourceLoader, this method is called if the page is called as a sub-element on a page not already loded with a I_CmsResourceLoader.

Specified by:
load in interface I_CmsResourceLoader
Parameters:
cms - the initialized CmsObject which provides user permissions
file - the requested OpenCms VFS resource
req - the servlet request
res - the servlet response
Throws:
javax.servlet.ServletException - might be thrown by the servlet environment
CmsException - in case of errors acessing OpenCms functions
java.io.IOException - might be thrown by the servlet environment
See Also:
I_CmsResourceLoader.load(org.opencms.file.CmsObject, org.opencms.file.CmsResource, javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse)

service

public void service(CmsObject cms,
                    CmsResource resource,
                    javax.servlet.ServletRequest req,
                    javax.servlet.ServletResponse res)
             throws javax.servlet.ServletException,
                    java.io.IOException,
                    CmsLoaderException
Description copied from interface: I_CmsResourceLoader
Does the job of including the requested resource, this method is called directly if the element is called as a sub-element from another I_CmsResourceLoader.

Specified by:
service in interface I_CmsResourceLoader
Parameters:
cms - used to access the OpenCms VFS
resource - the reqested resource in the VFS
req - the servlet request
res - the servlet response
Throws:
java.io.IOException - might be thrown by the servlet environment
javax.servlet.ServletException - might be thrown by the servlet environment
CmsLoaderException
See Also:
I_CmsResourceLoader.service(org.opencms.file.CmsObject, org.opencms.file.CmsResource, javax.servlet.ServletRequest, javax.servlet.ServletResponse)

setFlexCache

public void setFlexCache(CmsFlexCache cache)
Description copied from interface: I_CmsFlexCacheEnabledLoader
Will be called after the resource manager was initialized.

Specified by:
setFlexCache in interface I_CmsFlexCacheEnabledLoader
Parameters:
cache - the (optional) flex cache instance to use
See Also:
I_CmsFlexCacheEnabledLoader.setFlexCache(org.opencms.flex.CmsFlexCache)