org.apache.myfaces.trinidad.util

## Class URLEncoder

- java.lang.Object
- - org.apache.myfaces.trinidad.util.URLEncoder

- Direct Known Subclasses:
    URLEncoderWrapper

      public abstract class URLEncoder
      extends Object

  Encodes URL's based on thier type. While the ExternalContext does this to some extent, the types of URL's it encodes are often ill-defined. This utility method allows the caller to ensure that URL's are encoded in the proper fashion depending on which container is active at the time.

  Out of the box, this class supports Servlet and Portlet encoding, but it may be extended on a per-request basis to support other types of URL encoding with the use of the "registerURLEncoder" method.

  It is also important to note that this does not impact the encoding done by the ExternalContext. As such, all current applications should work without modification if they do not choose to use this API for encoding.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `URLEncoder()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract String` | `encodeActionURL(String url)` This function should be the same as the `ExternalContext.encodeActionURL(String)` method.
    `String` | `encodeBookmarkableURL(String url, Map<String,List<String>> params)` The purpose of this method is to generate a query string from the collection of Parameter objects provided by the parameters argument and append that query string to the baseUrl.
    `abstract String` | `encodeInProtocolResourceURL(String url)` Encodes a url to a resource such that it is inProtocol.
    `abstract String` | `encodePartialActionURL(String url)` This encodes a URL so that it can be used to make a PPR request in all containers.
    `abstract String` | `encodeRedirectURL(String url)` Encodes a url to be explicitly used for a redirect.
    `String` | `encodeRedirectURL(String url, Map<String,List<String>> parameters)` Encodes a url to be explicitly used for a redirect.
    `abstract String` | `encodeResourceURL(String url)` Encodes a url as a resource.
    `abstract String` | `encodeSkinResourceURL(String url)` Encodes a resource URL that is mapped to a skinning resources.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### URLEncoder

          public URLEncoder()

  - ### Method Detail

    - #### encodeActionURL

          public abstract String encodeActionURL(String url)

      This function should be the same as the `ExternalContext.encodeActionURL(String)` method. By default it call the code in the ExternalContext. The reason its provided here is that certain URLEncoderUtility instances may wish to override the default functionality and have the ExternalContext pull its default encoding from here.

    - #### encodePartialActionURL

          public abstract String encodePartialActionURL(String url)

      This encodes a URL so that it can be used to make a PPR request in all containers. JSF 2.0 has the ability to encode URL's in such a fashion, but this is missing from JSF 1.2 containers. This method provides the same functionality for JSF 1.2.
      Parameters:
        `url` - the unencoded url
      Returns:
        the encoded url
      Throws:
        `IllegalArgumentException` - if the URL cannot be encoded

    - #### encodeRedirectURL

          public abstract String encodeRedirectURL(String url)

      Encodes a url to be explicitly used for a redirect. In some containers, this is encoded as-is. In other containers this may not be encoded or must contain a fully qualified url. By default this method calls `#encodeRedirectURL(String,Map>)` with an empty parameter map.
      Parameters:
        `url` - the unencoded url
      Returns:
        the encoded url
      Throws:
        `IllegalArgumentException` - if the URL cannot be encoded

    - #### encodeRedirectURL

          public String encodeRedirectURL(String url,
                                 Map<String,List<String>> parameters)

      Encodes a url to be explicitly used for a redirect. In some containers, this is encoded as-is. In other containers this may not be encoded or must contain a fully qualified url. This version of the method allows for a map of parameters to be included in the URL. These parameters will generate a query string and add it to a URL that may or may-not already have its own existing query parameters. The parameter values should be encoded appropriately for the environment so that the resulting URL can be used at the target of the redirect. The default implementation throws and UnsupportedOperationException and is procided for the sole purpose of maintaining binary compatibility.
      Parameters:
        `url` - the unencoded url
      Returns:
        the encoded url
      Throws:
        `IllegalArgumentException` - if the URL cannot be encoded
        `UnsupportedOperationException` - if the implementation of the URLEncoder is not implemented.
      Since:
        2.1
      See Also:
        `ExternalContext.encodeRedirectURL(java.lang.String, java.util.Map<java.lang.String, java.util.List<java.lang.String>>)`

    - #### encodeResourceURL

          public abstract String encodeResourceURL(String url)

      Encodes a url as a resource. Generally speaking this will be equivalent to `ExternalContext.encodeResourceURL(String)`. The url returned from this method is NOT guarenteed to be in-protocol (meaning that it MAY not have access to session information). The advantage of encoding something in this fashion is that in certain types of containers, like portals, the URL generated may have faster access and will generally work better for the purposes of caching do to its RESTful state.
      Parameters:
        `url` - the unencoded url
      Returns:
        the encoded url
      Throws:
        `IllegalArgumentException` - if the URL cannot be encoded

    - #### encodeInProtocolResourceURL

          public abstract String encodeInProtocolResourceURL(String url)

      Encodes a url to a resource such that it is inProtocol. This means that the URL returned will be encoded in such a way that the resource will have access to the parent application's session. While these URL's do have access to the session information, they may not be written in a format that is easily cachable.
      Parameters:
        `url` - the unencoded url
      Returns:
        the encoded url
      Throws:
        `IllegalArgumentException` - if the URL cannot be encoded

    - #### encodeSkinResourceURL

          public abstract String encodeSkinResourceURL(String url)

      Encodes a resource URL that is mapped to a skinning resources. Trinidad has an extensive skinning system that allows for extraction of certain properties like images so that they can be used with the componentry. Generally these image resources are on the same server and whatnot as the actual skin. In a servlet environment, this is always the same server, but in portal-like environments these resources may be on different servers. This encodes a URL that comes from a skin and sends it to the right location.
      Parameters:
        `url` -
      Returns:

    - #### encodeBookmarkableURL

          public String encodeBookmarkableURL(String url,
                                     Map<String,List<String>> params)

      The purpose of this method is to generate a query string from the collection of Parameter objects provided by the parameters argument and append that query string to the baseUrl. This method must be able to encode the parameters to a baseUrl that may or may not have existing query parameters. The parameter values should be encoded appropriately for the environment so that the resulting URL can be used as the target of a link (e.g., in an href attribute) in a JSF response. It's possible for an ExternalContext implementation to override this method in any way that would make the URL bookmarkable in that environment.

      The default implementation simply throws an UnsupportedOperationException and is provided only for the purposes of ensuring binary compatibility.
      Parameters:
        `url` - the base url
        `params` - a map of parameters
      Returns:
      Throws:
        `UnsupportedOperationException` - if the default implementation does not support encoding of bookmarkable urls.

Copyright © 2001-2017 The Apache Software Foundation. All Rights Reserved.