oracle.portal.provider.v2.url
Class UrlUtils

java.lang.Object
  oracle.portal.provider.v2.url.UrlUtils

public class UrlUtils
extends java.lang.Object

Contains utility methods and constants for urls. There are utility methods in this class that are suited to rendering HTML, and others that are suited to rendering Oracle mobile XML (MXML) i.e. the markup used to satisfy requests for mime-type of oracle.portal.provider.v2.render.PortletRenderer.TYPE_MOBILE. Those methods that are safe for use in a MXML context are explitly labeled as such.

Field Summary

static int	BACK_LINK
static int	DESIGN_LINK
static int	EVENT_LINK
static int	LOGIN_LINK
static int	PAGE_LINK
static int	REFRESH_LINK
static int	REQUEST_LINK

Constructor Summary

UrlUtils()

Method Summary

static java.lang.String	absoluteLink(PortletRenderRequest pr, java.lang.String relativePath) Returns a fully-qualified URI for a path relative to the current request.
static java.lang.String	constructDetailHTMLLink(PortletRenderRequest pr, NameValue[] params, java.lang.String displayText, java.lang.String otherHtmlAttributes, boolean encodeParams, boolean replaceParams) Create a parameterized link for a portlet detail page By default, a portlet can have a single "detail" page that allows you to view portlet information in a full-screen mode.
static java.lang.String	constructHelpHTMLLink(PortletRenderRequest pr, NameValue[] params, java.lang.String displayText, java.lang.String otherHtmlAttributes, boolean encodeParams, boolean replaceParams) Create a parameterized link for a portlet help page By default, a portlet can have a single "help" page that allows you to display help information for your portlet in a full-screen mode.
static java.lang.String	constructHTMLLink(PortletRenderRequest pr, int linkType, java.lang.String displayText, java.lang.String otherHtmlAttributes, NameValue[] params, boolean encodeParams, boolean replaceParams) Generic utility to build a HTML link.
static java.lang.String	constructHTMLLink(PortletRenderRequest pr, int linkType, java.lang.String displayText, java.lang.String otherHtmlAttributes, NameValuePair[] params, boolean encodeParams, boolean replaceParams) Deprecated. use constructHTMLLink(PortletRenderRequest, int, String, String, NameValue[], boolean, boolean)
static java.lang.String	constructJavascriptLink(PortletRenderRequest pr, int linkType, NameValue[] params, boolean encodeParams, boolean replaceParams) Generic utility to generate a javascript call that append parameters to a link.
static java.lang.String	constructLink(PortletRenderRequest pr, int linkType, NameValue[] params, boolean encodeParams, boolean replaceParams) Generic utility to append parameters to a link.
static java.lang.String	constructLink(PortletRenderRequest pr, java.lang.String link, NameValue[] params, boolean encodeParams, boolean replaceParams) Generic utility to append parameters to a link.
static java.lang.String	constructMXMLLink(PortletRenderRequest pr, java.lang.String baseURI, java.lang.String displayText, java.lang.String otherAttributes, NameValue[] params, boolean encodeParams, boolean replaceParams) Generic utility to build a SimpleHref element.
static java.lang.String	constructResourceURL(PortletRenderRequest pr, java.lang.String resource) Utility to create a url that is proxied by portal to a resource Since there may be resources, such as images, that are accessible from the portal middle tier that are not available from the browser the user should be able to proxy requests through portal to get to these resources.
static java.lang.String	emitHiddenField(java.lang.String name, java.lang.String value) Utility to emit a single HTML hidden field with a specified name and value.
static java.lang.String	emitMxmlHiddenField(java.lang.String name, java.lang.String value) Utility to emit a single hidden SimpleFormItem field with a specified name and value (i.e. the markup used for satisfying requests of type oracle.portal.provider.v2.render.PortletRenderer.TYPE_MOBILE).
static java.lang.String	encodeParameter(java.lang.String param, PortletRenderRequest pr) Encodes a parameter for inclusion in a URL.
static java.lang.String	escapeString(java.lang.String text) Escapes the characters in a text string.
static java.lang.String	escapeStringByFlag(java.lang.String text) Escapes the characters in a text string.
static java.lang.String	htmlFormActionLink(PortletRenderRequest pr, int linkType) Transforms one of the various URIs known to the request into the appropriate form to be used in a FORM action tag.
static java.lang.String	htmlFormActionLink(java.lang.String ref) Transforms a URI into the appropriate form to be used in a FORM action tag.
static java.lang.String	htmlFormHiddenFields(PortletRenderRequest pr, int linkType) Enables the parameters in the query string to be POSTED when the form is submited.
static java.lang.String	htmlFormHiddenFields(PortletRenderRequest pr, int linkType, java.lang.String formName) Enables the parameters in the query string to be POSTED when the form is submited.
static java.lang.String	htmlFormHiddenFields(java.lang.String ref) Encodes the parameters in the query string of the passed URL as hidden form fields.
static java.lang.String	htmlFormName(PortletRenderRequest pr, java.lang.String formWithinPortletName) Generic utility to construct a unique name for a form on a portlet page In spite of it's name, this method is suitable for MXML.
static java.lang.String	imageString(java.lang.String image, java.lang.String imageAltText, java.lang.String imageName) Helper method for constructing an IMG HTML element
static java.lang.String	mxmlFormHiddenFields(java.lang.String ref) Encodes the parameters in the query string of the passed URL as hidden form fields suitable for use in a SimpleForm element (i.e.
static java.lang.String	parameterizeLink(PortletRenderRequest pr, int linkType, java.lang.String queryString) Adds new parameters to an existing link.
static java.lang.String	parameterizeLink(java.lang.String link, java.lang.String queryString) Adds new parameters to an existing link.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PAGE_LINK

public static final int PAGE_LINK

See Also:

Constant Field Values

DESIGN_LINK

public static final int DESIGN_LINK

See Also:

Constant Field Values

REQUEST_LINK

public static final int REQUEST_LINK

See Also:

Constant Field Values

LOGIN_LINK

public static final int LOGIN_LINK

See Also:

Constant Field Values

BACK_LINK

public static final int BACK_LINK

See Also:

Constant Field Values

EVENT_LINK

public static final int EVENT_LINK

See Also:

Constant Field Values

REFRESH_LINK

public static final int REFRESH_LINK

See Also:

Constant Field Values

Constructor Detail

UrlUtils

public UrlUtils()

Method Detail

imageString

public static java.lang.String imageString(java.lang.String image,
                                           java.lang.String imageAltText,
                                           java.lang.String imageName)

Helper method for constructing an IMG HTML element

Parameters:

image - name of the image to use.

imageAltText - Text description of the image, used by JAWS so blind person can know what the image does. can be null, empty or a string.

imageName - populates the "name" property - may be null.

Returns:

an IMG HTML element.

constructResourceURL

public static java.lang.String constructResourceURL(PortletRenderRequest pr,
                                                    java.lang.String resource)
                                             throws java.lang.IllegalArgumentException,
                                                    java.io.IOException

Utility to create a url that is proxied by portal to a resource Since there may be resources, such as images, that are accessible from the portal middle tier that are not available from the browser the user should be able to proxy requests through portal to get to these resources. This method returns a URL that does just that.

Parameters:

pr - render request

resource - the link to the resource.

Returns:

A URL that can be used to fetch the resource using the portal middle tier as a proxy.

Throws:

java.lang.IllegalArgumentException

java.io.IOException

constructHTMLLink

public static java.lang.String constructHTMLLink(PortletRenderRequest pr,
                                                 int linkType,
                                                 java.lang.String displayText,
                                                 java.lang.String otherHtmlAttributes,
                                                 NameValue[] params,
                                                 boolean encodeParams,
                                                 boolean replaceParams)
                                          throws java.lang.IllegalArgumentException,
                                                 java.io.IOException

Generic utility to build a HTML link. If UrlRewriting is being used it will generate <A onclick=javascriptMethod(params, replaceParams) otherHtmlAttributes>displayText</A> otherwise <A href=link+params otherHtmlAttributes>displayText </A> either way the generated HTML links behave in the same way.

Parameters:

pr - render request

linkType - the link to use. Constants representing these types are defined in UrlUtils.

displayText - text displayed for this link

otherHtmlAttributes - other attributes for the HTML link. No need for pre or end spaces in the string.

params - array of NameValue objects representing the parameters

encodeParams - flag indicating whether parameter names and values should be encoded

replaceParams - flag indicating whether parameters contained in the params array should replace existing parameters of the same name. true = replace or overwrite existing parameters. false = simply add parameters

Returns:

A HTML link eg <A ...>displayText</A>

Throws:

java.lang.IllegalArgumentException

java.io.IOException

constructHTMLLink

public static java.lang.String constructHTMLLink(PortletRenderRequest pr,
                                                 int linkType,
                                                 java.lang.String displayText,
                                                 java.lang.String otherHtmlAttributes,
                                                 NameValuePair[] params,
                                                 boolean encodeParams,
                                                 boolean replaceParams)
                                          throws java.lang.IllegalArgumentException,
                                                 java.io.IOException

Deprecated. use constructHTMLLink(PortletRenderRequest, int, String, String, NameValue[], boolean, boolean)

DEPRECATED Generic utility to build a HTML link. If UrlRewriting is being used it will generate <A onclick=javascriptMethod(params, replaceParams) otherHtmlAttributes>displayText</A> otherwise <A href=link+params otherHtmlAttributes>displayText </A> either way the generated HTML links behave in the same way.

Parameters:

pr - render request

linkType - the link to use. Constants representing these types are defined in UrlUtils.

displayText - text displayed for this link

otherHtmlAttributes - other attributes for the HTML link. No need for pre or end spaces in the string.

params - array of NameValuePair objects representing the parameters

encodeParams - flag indicating whether parameter names and values should be encoded

replaceParams - flag indicating whether parameters contained in the params array should replace existing parameters of the same name. true = replace or overwrite existing parameters. false = simply add parameters

Returns:

A HTML link eg <A ...>displayText</A>

Throws:

java.lang.IllegalArgumentException

java.io.IOException

constructJavascriptLink

public static java.lang.String constructJavascriptLink(PortletRenderRequest pr,
                                                       int linkType,
                                                       NameValue[] params,
                                                       boolean encodeParams,
                                                       boolean replaceParams)
                                                throws java.lang.IllegalArgumentException,
                                                       java.io.IOException

Generic utility to generate a javascript call that append parameters to a link.

Parameters:

pr - render request

linkType - the link to use. Constants representing these types are defined in UrlUtils.

params - array of NameValue objects representing the parameters

encodeParams - flag indicating whether parameter names and values should be encoded

replaceParams - flag indicating whether parameters contained in the params array should replace existing parameters of the same name. true = replace or overwrite existing parameters. false = simply add parameters

Returns:

call to a javascript function that will append the parameters to a link and call that link

Throws:

java.lang.IllegalArgumentException

java.io.IOException

htmlFormName

public static java.lang.String htmlFormName(PortletRenderRequest pr,
                                            java.lang.String formWithinPortletName)

Generic utility to construct a unique name for a form on a portlet page In spite of it's name, this method is suitable for MXML. The form name is "f" + portletRef + formWithinPortletName eg f73_35680_73_35673_35673

Parameters:

pr - render request

formWithinPortletName - There may be more than one form per portlet this name is used to destinguish between different forms within a portlet. This may be null or empty if there is only one form in a portlet.

Returns:

A form name that is unique on a portal page

constructLink

public static java.lang.String constructLink(PortletRenderRequest pr,
                                             int linkType,
                                             NameValue[] params,
                                             boolean encodeParams,
                                             boolean replaceParams)
                                      throws java.lang.IllegalArgumentException,
                                             java.io.IOException

Generic utility to append parameters to a link. This method is suitable for use in a MXML context, but only if URL rewriting is not in operation - in this case no error will be issued.

Parameters:

pr - render request

linkType - the link to use. Constants representing these types are defined in UrlUtils.

params - array of NameValue objects representing the parameters

encodeParams - flag indicating whether parameter names and values should be encoded

replaceParams - flag indicating whether parameters contained in the params array should replace existing parameters of the same name. true = replace or overwrite existing parameters. false = simply add parameters

Returns:

original link with additional parameters or a javascript call to the original link with additional parameters.

Throws:

java.lang.IllegalArgumentException

java.io.IOException

constructLink

public static java.lang.String constructLink(PortletRenderRequest pr,
                                             java.lang.String link,
                                             NameValue[] params,
                                             boolean encodeParams,
                                             boolean replaceParams)
                                      throws java.lang.IllegalArgumentException,
                                             java.io.IOException

Generic utility to append parameters to a link.

Parameters:

pr - render request

link - the link to be parameterized

params - array of NameValue objects representing the parameters

encodeParams - flag indicating whether parameter names and values should be encoded

replaceParams - flag indicating whether parameters contained in the params array should replace existing parameters of the same name. true = replace or overwrite existing parameters. false = simply add parameters

Returns:

original link with additional parameters.

Throws:

java.lang.IllegalArgumentException

java.io.IOException

htmlFormHiddenFields

public static java.lang.String htmlFormHiddenFields(PortletRenderRequest pr,
                                                    int linkType)
                                             throws java.lang.IllegalArgumentException

Enables the parameters in the query string to be POSTED when the form is submited. This code generates hidden parameters when rewriteUrls is false or by setting the action value of the form to be the whole url when rewriteUrls is true. This function can only be used if there are only one form on a portlet. This utility method either generates the hidden field tags from this that will alter the forms action to be the URL and returns the javascript as a String.

Parameters:

pr - the request

linkType - the link to use. Constants representing these types are defined in UrlUtils.

Throws:

java.lang.IllegalArgumentException

htmlFormHiddenFields

public static java.lang.String htmlFormHiddenFields(PortletRenderRequest pr,
                                                    int linkType,
                                                    java.lang.String formName)
                                             throws java.lang.IllegalArgumentException

Enables the parameters in the query string to be POSTED when the form is submited. This code generates hidden parameters when rewriteUrls is false or by setting the action value of the form to be the whole url when rewriteUrls is true. This utility method either generates the hidden field tags from this URL and returns them as a String. Or generates a javascript fragment that will alter the forms action to be the URL and returns the javascript as a String.

Parameters:

pr - the request

linkType - the link to use. Constants representing these types are defined in PortletRendererUtil.

formName - unique name of a form within a page. Use htmlFormName() to generate this name.

Throws:

java.lang.IllegalArgumentException

htmlFormHiddenFields

public static java.lang.String htmlFormHiddenFields(java.lang.String ref)

Encodes the parameters in the query string of the passed URL as hidden form fields. When "linking" back to the portlet via a form, the URI parameters must be added as hidden fields. These parameters are found in the querystring of your URI. This utility method generates the hidden field tags from this URL and returns them as a String.

Parameters:

ref - the URI

emitHiddenField

public static java.lang.String emitHiddenField(java.lang.String name,
                                               java.lang.String value)

Utility to emit a single HTML hidden field with a specified name and value.

Parameters:

name - the encoded name of the hidden field

value - the encoded value of the hidden field

Returns:

a string containing the HTML hidden field markup

encodeParameter

public static java.lang.String encodeParameter(java.lang.String param,
                                               PortletRenderRequest pr)
                                        throws java.io.IOException

Encodes a parameter for inclusion in a URL. Parameter is encoded using the same character set that was used when the portal encoded the request parameters. The character sets must be the same so that parameters that may be intended for another portlet implemented in pl/sql can decode them correctly. This method is suitable for use in a MXML context.

Parameters:

param - the parameter to be encoded

pr - PortletRenderRequest object for this request

Returns:

encoded parameter, suitable for inclusion in a URL

Throws:

java.io.IOException

parameterizeLink

public static java.lang.String parameterizeLink(PortletRenderRequest pr,
                                                int linkType,
                                                java.lang.String queryString)
                                         throws java.lang.IllegalArgumentException

Adds new parameters to an existing link. There are various links available to the portlet for use while rendering its response. This utility method conveniently adds parameters to one of these links. The method overrides existing parameters is they exist. I.e. existing (queryString) parameters will be removed if it duplicates (by name) a new parameter.

Parameters:

pr - the request.

linkType - the id for the link we want to parameterize. ID constants are defined IN UrlUtils

queryString - the parameters to be added in properly encodes queryString form. the String should begin with the first parameter name not a "?".

Throws:

java.lang.IllegalArgumentException

parameterizeLink

public static java.lang.String parameterizeLink(java.lang.String link,
                                                java.lang.String queryString)

Adds new parameters to an existing link. There are various links available to the portlet for use while rendering its response. This utility method conveniently adds parameters to one of these links. The method overrides existing parameters is they exist. I.e. existing (queryString) parameters will be removed if it duplicates (by name) a new parameter.

Parameters:

link - the link to add parameters to.

queryString - the parameters to be added in properly encodes queryString form. The String should begin with the first parameter name not a "?".

absoluteLink

public static java.lang.String absoluteLink(PortletRenderRequest pr,
                                            java.lang.String relativePath)

Returns a fully-qualified URI for a path relative to the current request. As Web (Http) Portlets are called indirectly via the portal the client browser's current path is to the portal not to the portlet. Because of this all HREFs must be expressed using fully qualified paths vs. the traditional relative paths. This method allows you to properly encode a relative path. Note: this is equivalent to portletLink(). I.e the method only differs when the renderer is reached via a "forward" as is the case with a servlet or JSP. This method is suitable for use in a MXML context.

Parameters:

pr - the PortletRenderRequest

relativePath - the path we want to make absolute

htmlFormActionLink

public static java.lang.String htmlFormActionLink(java.lang.String ref)

Transforms a URI into the appropriate form to be used in a FORM action tag. In spite of it's name, this method is suitable for use in a MXML context.

Parameters:

ref - the URI to be transformed

htmlFormActionLink

public static java.lang.String htmlFormActionLink(PortletRenderRequest pr,
                                                  int linkType)
                                           throws java.lang.IllegalArgumentException

Transforms one of the various URIs known to the request into the appropriate form to be used in a FORM action tag.

Parameters:

pr - the PortletRenderRequest

linkType - the link in this request that should be used.

Throws:

java.lang.IllegalArgumentException

constructDetailHTMLLink

public static java.lang.String constructDetailHTMLLink(PortletRenderRequest pr,
                                                       NameValue[] params,
                                                       java.lang.String displayText,
                                                       java.lang.String otherHtmlAttributes,
                                                       boolean encodeParams,
                                                       boolean replaceParams)
                                                throws PortletException,
                                                       java.io.IOException

Create a parameterized link for a portlet detail page By default, a portlet can have a single "detail" page that allows you to view portlet information in a full-screen mode. This methods allows you to create many "detail" links with different sets of parameters. You can use these links anywhere in the body of your portlet to create a portlet that has more than one detail page. When a user clicks on a detail link within your portlet, your portlet will be called and the renderer associated with "detail" mode will be invoked. You can use the parameters you add to the detail link to determine which "detail page" the renderer should emit.

Parameters:

pr - the render request.

params - an array of NameValue objects representing the parameter names and associated values. Names cannot be NULL

displayText - text displayed for this link

otherHtmlAttributes - other attributes for the HTML link. No need for pre or end spaces in the string.

encodeParams - flag indicating whether the parameter names and values should be URL encoded using the multibyte URL encoder.

replaceParams - flag indicating whether parameters contained in the params array should replace existing parameters of the same name. true = replace or overwrite existing parameters. false = simply add parameters

Throws:

PortletException

java.io.IOException

constructHelpHTMLLink

public static java.lang.String constructHelpHTMLLink(PortletRenderRequest pr,
                                                     NameValue[] params,
                                                     java.lang.String displayText,
                                                     java.lang.String otherHtmlAttributes,
                                                     boolean encodeParams,
                                                     boolean replaceParams)
                                              throws PortletException,
                                                     java.io.IOException

Create a parameterized link for a portlet help page By default, a portlet can have a single "help" page that allows you to display help information for your portlet in a full-screen mode. This methods allows you to create many "help" links with different sets of parameters. You can use these links anywhere in the body of your portlet to create context sensitive help pages. When a user clicks on a help link within your portlet, your portlet will be called and the renderer associated with "help" mode will be invoked. You can use the parameters you add to the detail link to determine which "help page" the renderer should emit.

Parameters:

pr - the render request.

params - an array of NameValue objects representing the parameter names and associated values. Names cannot be NULL

displayText - text displayed for this link

otherHtmlAttributes - other attributes for the HTML link. No need for pre or end spaces in the string.

encodeParams - flag indicating whether the parameter names and values should be URL encoded using the multibyte URL encoder.

replaceParams - flag indicating whether parameters contained in the params array should replace existing parameters of the same name. true = replace or overwrite existing parameters. false = simply add parameters

Throws:

PortletException

java.io.IOException

mxmlFormHiddenFields

public static java.lang.String mxmlFormHiddenFields(java.lang.String ref)

Encodes the parameters in the query string of the passed URL as hidden form fields suitable for use in a SimpleForm element (i.e. the markup used for satisfying requests of mime-type oracle.portal.provider.v2.render.PortletRenderer.TYPE_MOBILE). When "linking" back to the portlet via a form, the URI parameters must be added as hidden fields. These parameters are found in the querystring of your URI. This utility method generates the hidden SimpleFormeItem elements from the URL and returns them as a String suitable for placement within a SimpleForm.

Parameters:

ref - the URI containing the parameters to be included as hidden fields in the form.

emitMxmlHiddenField

public static java.lang.String emitMxmlHiddenField(java.lang.String name,
                                                   java.lang.String value)

Utility to emit a single hidden SimpleFormItem field with a specified name and value (i.e. the markup used for satisfying requests of type oracle.portal.provider.v2.render.PortletRenderer.TYPE_MOBILE). The method will XML-escape the name and value within the SimpleFormItem element that is to be returned, the caller does not have to do this.

Parameters:

name - the encoded name of the hidden field

value - the encoded value of the hidden field

Returns:

a string containing a hidden SimpleFormItem element.

constructMXMLLink

public static java.lang.String constructMXMLLink(PortletRenderRequest pr,
                                                 java.lang.String baseURI,
                                                 java.lang.String displayText,
                                                 java.lang.String otherAttributes,
                                                 NameValue[] params,
                                                 boolean encodeParams,
                                                 boolean replaceParams)
                                          throws java.lang.IllegalArgumentException,
                                                 java.io.IOException

Generic utility to build a SimpleHref element. This method does not support UrlRewriting. It is to be used when rendering a link in the markup used to satisfy requests with mime-type oracle.portal.provider.v2.render.PortletRenderer.TYPE_MOBILE.

Parameters:

pr - the portlet render request

baseURI - the link on which to base the target of the SimpleHref.

displayText - text displayed for this link

otherAttributes - other attributes for the SimpleHref's target. No need for pre or end spaces in the string.

params - array of NameValue objects representing the parameters

encodeParams - flag indicating whether parameter names and values should be encoded

replaceParams - flag indicating whether parameters contained in the params array should replace existing parameters of the same name. true = replace or overwrite existing parameters. false = simply add parameters

Returns:

A SimpleHref element, e.g. <SimpleHref target="http://...">displayText</SimpleHref>

Throws:

java.lang.IllegalArgumentException

java.io.IOException

escapeString

public static java.lang.String escapeString(java.lang.String text)

Escapes the characters in a text string. This is used to ensure that rendered text in a browser does not contain executable malicious script.

Parameters:

text - the string that is to be escaped

escapeStringByFlag

public static java.lang.String escapeStringByFlag(java.lang.String text)

Escapes the characters in a text string. This is used to ensure that rendered text in a browser does not contain executable malicious script. There might be rare cases where the markup in a piece of text is supposed to be executed by a browser, e.g. bold tags in a title. The ability to do this is switched on and off as a global JNDI environment variable, oracle/portal/provider/v2/global/escapeStrings. It is off by default since unescaped text strings are insecure and allow cross site scripting attacks. This version of the method has behaviour that is driven by the global flag. In most cases this would be considered insecure and the method escapeString(String) should be used instead.

Parameters:

text - the text to be escaped