org.apache.velocity.tools.struts
Class SecureLinkTool

java.lang.Object
  org.apache.velocity.tools.generic.SafeConfig
      org.apache.velocity.tools.generic.LinkTool
          org.apache.velocity.tools.view.LinkTool
              org.apache.velocity.tools.struts.SecureLinkTool

All Implemented Interfaces:

java.lang.Cloneable

public class SecureLinkTool
extends LinkTool

Tool to be able to use Struts SSL Extensions with Velocity.

It has the same interface as StrutsLinkTool and can function as a substitute if Struts 1.x and SSL Ext are installed.

The SecureLinkTool extends the standard LinkTool and has the exact same interface as StrutsLinkTool and the same function. It should substitute the StrutsLinkTool in the toolbox if SSL Ext is installed. It's functionality is a subset of the functionality provided by the sslext tag library for JSP.

The SSL Ext. Struts extension package makes it possible to declare Struts actions secure, non-secure, or neutral in the struts config like so:

 <action path="/someSecurePath" type="some.important.Action">
     <set-property property="secure" value="true"/>
     <forward name="success" path="/somePage.vm" />
 </action>
 

If an action is declared secure the SecureLinkTool will render the relevant link as https (if not already in ssl-mode). In the same way, if an action is declared non-secure the SecureLinkTool will render the relevant link as http (if in ssl-mode). If the action is declared as neutral (with a "secure" property of "any") then the SecureLinkTool won't force a protocol change either way.
If the custom request processor is also used then a request will be redirected to the correct protocol if an action URL is manually entered into the browser with the wrong protocol

These are the steps needed to enable SSL Ext:

• SSL connections need to be enabled on the webserver.
• The Java Secure Socket Extension (JSSE) package needs to be in place (it's integrated into the Java 2 SDK Standard Edition, v. 1.4 but optional for earlier versions)
• In your tools.xml, add the SecureLinkTool to replace (same key) or complement (alternate key) the StrutsLinkTool
• In struts-conf.xml the custom action-mapping class needs to be specified
• In struts-conf.xml the custom controller class can optionally be specified (if the redirect feature is wanted)
• In struts-conf.xml the SecurePlugIn needs to be added
• In struts-conf.xml, when using Tiles, the SecureTilesPlugin substitues both the TilesPlugin and the SecurePlugIn and it also takes care of setting the correct controller so there is no need to specify the custom controller.

See SSL Ext.project home for more info.

Usage:

 Template example:
 <!-- Use just like a regular StrutsLinkTool -->
 $link.action.nameOfAction
 $link.action.nameOfForward

 If the action or forward is marked as secure, or not,
 in your struts-config then the link will be rendered
 with https or http accordingly.

 Toolbox configuration:
 <tools>
   <toolbox scope="request">
     <tool class="org.apache.velocity.tools.struts.SecureLinkTool"/>
   </toolbox>
 </tools>
 

Since:

VelocityTools 1.1

Version:

$Revision: 707788 $ $Date: 2008-10-24 16:28:06 -0700 (Fri, 24 Oct 2008) $

Author:

Marino A. Jonsson

Field Summary

protected javax.servlet.ServletContext	application
private static java.lang.String	HTTP
private static java.lang.String	HTTPS
private static java.lang.String	STD_HTTP_PORT
private static java.lang.String	STD_HTTPS_PORT

Fields inherited from class org.apache.velocity.tools.view.LinkTool

INCLUDE_REQUEST_PARAMS_KEY, includeRequestParams, request, response

Fields inherited from class org.apache.velocity.tools.generic.LinkTool

APPEND_PARAMS_KEY, appendParams, charset, CHARSET_KEY, DEFAULT_CHARSET, DEFAULT_SCHEME, FORCE_RELATIVE_KEY, forceRelative, fragment, FRAGMENT_KEY, host, HOST_KEY, HTML_QUERY_DELIMITER, LOG, opaque, path, PATH_KEY, port, PORT_KEY, query, QUERY_KEY, queryDelim, scheme, SCHEME_KEY, SECURE_SCHEME, self, URI_KEY, user, USER_KEY, XHTML_MODE_KEY, XHTML_QUERY_DELIMITER

Fields inherited from class org.apache.velocity.tools.generic.SafeConfig

LOCK_CONFIG_KEY, OLD_LOCK_CONFIG_KEY, SAFE_MODE_KEY

Constructor Summary

SecureLinkTool()

Method Summary

java.lang.String	computeURL(javax.servlet.http.HttpServletRequest request, javax.servlet.ServletContext app, java.lang.String link) Compute a hyperlink URL based on the specified action link.
protected void	configure(ValueParser props) Does the actual configuration.
private static org.apache.struts.config.SecureActionConfig	getActionConfig(javax.servlet.ServletContext app, java.lang.String linkString) Finds the configuration definition for the specified action link
SecureLinkTool	setAction(java.lang.String action) Returns a copy of the link with the given action name converted into a server-relative URI reference.
SecureLinkTool	setForward(java.lang.String forward) Returns a copy of the link with the given global forward name converted into a server-relative URI reference.
private static java.lang.StringBuilder	startNewUrlString(javax.servlet.http.HttpServletRequest request, java.lang.String desiredScheme, java.lang.String desiredPort) Builds the protocol, server name, and port portion of the new URL
java.lang.String	toEncoded(java.lang.String url, java.lang.String sessionId) Return the specified URL with the specified session identifier suitably encoded.

Methods inherited from class org.apache.velocity.tools.view.LinkTool

addMissingRequestParams, addRequestParams, addRequestParamsExcept, getContextPath, getContextURL, getRequestPath, isPathChanged, setFromRequest, setIncludeRequestParams, toString

Methods inherited from class org.apache.velocity.tools.generic.LinkTool

absolute, absolute, anchor, append, append, appendAsArray, appendPath, appendQuery, combinePath, combineQuery, createURI, debug, debug, decode, decodeQueryPercents, directory, duplicate, duplicate, encode, equals, getAnchor, getAppendParams, getBaseRef, getCharacterEncoding, getDirectory, getFile, getHost, getParams, getPath, getPort, getQuery, getRoot, getScheme, getSelf, getUri, getUser, handleParamsBoolean, hashCode, host, insecure, isAbsolute, isOpaque, isRelative, isSecure, isXHTML, normalizeQuery, param, params, parseQuery, parseQuery, path, port, query, relative, relative, remove, removeParam, root, scheme, secure, set, setAppendParams, setCharacterEncoding, setForceRelative, setFragment, setFromURI, setHost, setParam, setParams, setPath, setPort, setQuery, setScheme, setUserInfo, setXHTML, toQuery, toQuery, toURI, uri, user

Methods inherited from class org.apache.velocity.tools.generic.SafeConfig

configure, isConfigLocked, isSafeMode, setLockConfig, setSafeMode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

application

protected javax.servlet.ServletContext application

HTTP

private static final java.lang.String HTTP

See Also:

Constant Field Values

HTTPS

private static final java.lang.String HTTPS

See Also:

Constant Field Values

STD_HTTP_PORT

private static final java.lang.String STD_HTTP_PORT

See Also:

Constant Field Values

STD_HTTPS_PORT

private static final java.lang.String STD_HTTPS_PORT

See Also:

Constant Field Values

Constructor Detail

SecureLinkTool

public SecureLinkTool()

Method Detail

configure

protected void configure(ValueParser props)

Description copied from class: SafeConfig

Does the actual configuration. This is protected, so subclasses may share the same ValueParser and call configure at any time, while preventing templates from doing so when configure(Map) is locked.

Overrides:

configure in class LinkTool

setAction

public SecureLinkTool setAction(java.lang.String action)

Returns a copy of the link with the given action name converted into a server-relative URI reference. This method does not check if the specified action really is defined. This method will overwrite any previous URI reference settings but will copy the query string.

Parameters:

action - an action path as defined in struts-config.xml

Returns:

a new instance of StrutsLinkTool

setForward

public SecureLinkTool setForward(java.lang.String forward)

Returns a copy of the link with the given global forward name converted into a server-relative URI reference. If the parameter does not map to an existing global forward name, null is returned. This method will overwrite any previous URI reference settings but will copy the query string.

Parameters:

forward - a global forward name as defined in struts-config.xml

Returns:

a new instance of StrutsLinkTool

computeURL

public java.lang.String computeURL(javax.servlet.http.HttpServletRequest request,
                                   javax.servlet.ServletContext app,
                                   java.lang.String link)

Compute a hyperlink URL based on the specified action link. The returned URL will have already been passed to response.encodeURL() for adding a session identifier.

Parameters:

request - the current request.

app - the current ServletContext.

link - the action that is to be converted to a hyperlink URL

Returns:

the computed hyperlink URL

getActionConfig

private static org.apache.struts.config.SecureActionConfig getActionConfig(javax.servlet.ServletContext app,
                                                                           java.lang.String linkString)

Finds the configuration definition for the specified action link

Parameters:

app - the current ServletContext.

linkString - The action we are searching for, specified as a link. (i.e. may include "..")

Returns:

The SecureActionConfig object entry for this action, or null if not found

startNewUrlString

private static java.lang.StringBuilder startNewUrlString(javax.servlet.http.HttpServletRequest request,
                                                         java.lang.String desiredScheme,
                                                         java.lang.String desiredPort)

Builds the protocol, server name, and port portion of the new URL

Parameters:

request - The current request

desiredScheme - The scheme (http or https) to be used in the new URL

desiredPort - The port number to be used in th enew URL

Returns:

The new URL as a StringBuilder

toEncoded

public java.lang.String toEncoded(java.lang.String url,
                                  java.lang.String sessionId)

Return the specified URL with the specified session identifier suitably encoded.

Parameters:

url - URL to be encoded with the session id

sessionId - Session id to be included in the encoded URL

Returns:

the specified URL with the specified session identifier suitably encoded