[myfaces-trinidad] 03/03: Beefed up some javadoc

[de...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

deki pushed a commit to branch sobryan-experimental-url-encoding-2
in repository https://gitbox.apache.org/repos/asf/myfaces-trinidad.git

commit d1516d490b364524e9f891e266633268170603f8
Author: Scott Bryan <so...@apache.org>
AuthorDate: Tue Jun 26 21:19:45 2012 +0000

    Beefed up some javadoc
---
 .../apache/myfaces/trinidad/util/URLEncoder.java   | 46 ++++++++++++++++------
 1 file changed, 35 insertions(+), 11 deletions(-)

diff --git a/trinidad-api/src/main/java/org/apache/myfaces/trinidad/util/URLEncoder.java b/trinidad-api/src/main/java/org/apache/myfaces/trinidad/util/URLEncoder.java
index 614c0c7..0d1c9b5 100644
--- a/trinidad-api/src/main/java/org/apache/myfaces/trinidad/util/URLEncoder.java
+++ b/trinidad-api/src/main/java/org/apache/myfaces/trinidad/util/URLEncoder.java
@@ -32,30 +32,54 @@ public abstract class URLEncoder
   
   /**
    * 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.
    * 
-   * @param url
-   * @return
+   * @param url the unencoded url
+   * @return the encoded url
+   * 
+   * @throws IllegalArgumentException if the URL cannot be encoded
    */
   public abstract String encodePartialActionURL(String url);
   
   /**
-   * Encodes a url for redirect.
+   * 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.
    * 
-   * @param url
-   * @return
+   * @param url the unencoded url
+   * @return the encoded url
+   * 
+   * @throws IllegalArgumentException if the URL cannot be encoded
    */
   public abstract String encodeRedirectURL(String url);
   
+  /**
+   * Encodes a url as a resource.  Generally speaking this will be equivalent to
+   * {@link 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.
+   * 
+   * @param url the unencoded url
+   * @return the encoded url
+   * 
+   * @throws IllegalArgumentException if the URL cannot be encoded
+   */
   public abstract String encodeResourceURL(String url);
   
   /**
-   * Encodes a url to a static resource.  This url *MAY* share the same session
-   * as the overall page or it may not.  The advantage of encoding something as
-   * a static resource is that in certain types of containers, like portals, the
-   * URL generated by this encoding may work better for the purposes of caching.
+   * 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.
    * 
-   * @param url
-   * @return
+   * @param url the unencoded url
+   * @return the encoded url
+   * 
+   * @throws IllegalArgumentException if the URL cannot be encoded
    */
   public abstract String encodeInProtocolResourceURL(String url);
   

-- 
To stop receiving notification emails like this one, please contact
"commits@myfaces.apache.org" <co...@myfaces.apache.org>.