1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.myfaces.trinidad.util;
20
21 import java.io.Serializable;
22
23 import java.io.UnsupportedEncodingException;
24
25 import java.util.Collections;
26 import java.util.List;
27 import java.util.Map;
28
29 import javax.faces.context.ExternalContext;
30 import javax.faces.context.FacesContext;
31
32 /**
33 * Encodes URL's based on thier type. While the ExternalContext does this to
34 * some extent, the types of URL's it encodes are often ill-defined. This utility
35 * method allows the caller to ensure that URL's are encoded in the proper fashion
36 * depending on which container is active at the time.
37 * <p/>
38 * Out of the box, this class supports Servlet and Portlet encoding, but it may
39 * be extended on a per-request basis to support other types of URL encoding with
40 * the use of the "registerURLEncoder" method.
41 * <p/>
42 * It is also important to note that this does not impact the encoding done by the
43 * ExternalContext. As such, all current applications should work without
44 * modification if they do not choose to use this API for encoding.
45 */
46 public abstract class URLEncoder
47 {
48 /**
49 * This function should be the same as the {@link ExternalContext#encodeActionURL(String)}
50 * method. By default it call the code in the ExternalContext. The reason its
51 * provided here is that certain URLEncoderUtility instances may wish to override
52 * the default functionality and have the ExternalContext pull its default encoding
53 * from here.
54 */
55 public abstract String encodeActionURL(String url);
56
57 /**
58 * This encodes a URL so that it can be used to make a PPR request in all containers.
59 * JSF 2.0 has the ability to encode URL's in such a fashion, but this is missing
60 * from JSF 1.2 containers. This method provides the same functionality for JSF 1.2.
61 *
62 * @param url the unencoded url
63 * @return the encoded url
64 *
65 * @throws IllegalArgumentException if the URL cannot be encoded
66 */
67 public abstract String encodePartialActionURL(String url);
68
69 /**
70 * Encodes a url to be explicitly used for a redirect. In some containers, this is
71 * encoded as-is. In other containers this may not be encoded or must contain a
72 * fully qualified url. By default this method calls {@link #encodeRedirectURL(String,Map<String,List<String>>)}
73 * with an empty parameter map.
74 *
75 * @param url the unencoded url
76 * @return the encoded url
77 *
78 * @throws IllegalArgumentException if the URL cannot be encoded
79 */
80 public abstract String encodeRedirectURL(String url);
81
82 /**
83 * Encodes a url to be explicitly used for a redirect. In some containers, this is
84 * encoded as-is. In other containers this may not be encoded or must contain a
85 * fully qualified url. This version of the method allows for a map of parameters
86 * to be included in the URL. These parameters will generate a query string and add
87 * it to a URL that may or may-not already have its own existing query parameters.
88 * The parameter values should be encoded appropriately for the environment so that
89 * the resulting URL can be used at the target of the redirect.
90 *
91 * The default implementation throws and UnsupportedOperationException and is procided
92 * for the sole purpose of maintaining binary compatibility.
93 *
94 * @param url the unencoded url
95 * @return the encoded url
96 * @throws IllegalArgumentException if the URL cannot be encoded
97 * @throws UnsupportedOperationException if the implementation of the URLEncoder is not implemented.
98 *
99 * @since 2.1
100 * @see ExternalContext#encodeRedirectURL
101 */
102 public String encodeRedirectURL(String url, Map<String, List<String>> parameters)
103 {
104 throw new UnsupportedOperationException();
105 }
106
107 /**
108 * Encodes a url as a resource. Generally speaking this will be equivalent to
109 * {@link ExternalContext#encodeResourceURL(String)}. The url returned from this
110 * method is NOT guarenteed to be in-protocol (meaning that it MAY not have access
111 * to session information). The advantage of encoding something in this fashion
112 * is that in certain types of containers, like portals, the URL generated may
113 * have faster access and will generally work better for the purposes of caching
114 * do to its RESTful state.
115 *
116 * @param url the unencoded url
117 * @return the encoded url
118 *
119 * @throws IllegalArgumentException if the URL cannot be encoded
120 */
121 public abstract String encodeResourceURL(String url);
122
123 /**
124 * Encodes a url to a resource such that it is inProtocol. This means that the
125 * URL returned will be encoded in such a way that the resource will have access
126 * to the parent application's session. While these URL's do have access to the
127 * session information, they may not be written in a format that is easily cachable.
128 *
129 * @param url the unencoded url
130 * @return the encoded url
131 *
132 * @throws IllegalArgumentException if the URL cannot be encoded
133 */
134 public abstract String encodeInProtocolResourceURL(String url);
135
136 /**
137 * Encodes a resource URL that is mapped to a skinning resources. Trinidad has
138 * an extensive skinning system that allows for extraction of certain properties
139 * like images so that they can be used with the componentry. Generally these
140 * image resources are on the same server and whatnot as the actual skin. In
141 * a servlet environment, this is always the same server, but in portal-like
142 * environments these resources may be on different servers. This encodes a
143 * URL that comes from a skin and sends it to the right location.
144 *
145 * @param url
146 * @return
147 */
148 public abstract String encodeSkinResourceURL(String url);
149
150 /**
151 * The purpose of this method is to generate a query string from the collection of Parameter
152 * objects provided by the parameters argument and append that query string to the baseUrl. This
153 * method must be able to encode the parameters to a baseUrl that may or may not have existing
154 * query parameters. The parameter values should be encoded appropriately for the environment
155 * so that the resulting URL can be used as the target of a link (e.g., in an href attribute) in
156 * a JSF response. It's possible for an ExternalContext implementation to override this method in
157 * any way that would make the URL bookmarkable in that environment.
158 * <p/>
159 * The default implementation simply throws an UnsupportedOperationException and is provided only
160 * for the purposes of ensuring binary compatibility.
161 *
162 * @param url the base url
163 * @param params a map of parameters
164 * @return
165 *
166 * @throws UnsupportedOperationException if the default implementation does not support encoding
167 * of bookmarkable urls.
168 */
169 public String encodeBookmarkableURL(String url, Map<String, List<String>> params)
170 {
171 throw new UnsupportedOperationException();
172 }
173 }