View Javadoc

1   /*
2    * $Id: URL.java 753015 2009-03-12 21:00:23Z musachy $
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *  http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  package org.apache.struts2.components;
23  
24  import java.io.Writer;
25  
26  import javax.servlet.http.HttpServletRequest;
27  import javax.servlet.http.HttpServletResponse;
28  
29  import org.apache.struts2.StrutsConstants;
30  import org.apache.struts2.views.annotations.StrutsTag;
31  import org.apache.struts2.views.annotations.StrutsTagAttribute;
32  
33  import com.opensymphony.xwork2.inject.Inject;
34  import com.opensymphony.xwork2.util.ValueStack;
35  import com.opensymphony.xwork2.util.logging.Logger;
36  import com.opensymphony.xwork2.util.logging.LoggerFactory;
37  
38  /***
39   * <!-- START SNIPPET: javadoc -->
40   *
41   * <p>This tag is used to create a URL.</p>
42   *
43   * <p>You can use the &lt;param&gt; tag inside the body to provide
44   * additional request parameters. If the value of a param is an Array or
45   * an Iterable all the values will be added to the URL.</p>
46   *
47   * <b>NOTE:</b>
48   * <p>By default request parameters will be separated using escaped ampersands (i.e., &amp;amp;).
49   * This is necessary for XHTML compliance, however, when using the URL generated by this tag
50   * with the &lt;s:property&gt; tag, the <b>escapeAmp</b> attribute should be used to disable
51   * ampersand escaping.</p>
52   *
53   * <b>NOTE:</b>
54   * <p>When includeParams is 'all' or 'get', the parameter defined in a &lt;param&gt;
55   * tag will take precedence over any params included due to the includeParams attribute. For
56   * example, in Example 3 below, if there is a id parameter in the url where the page this
57   * tag is included like http://&lt;host&gt;:&lt;port&gt;/&lt;context&gt;/editUser.action?id=3333&name=John
58   * the generated url will be http://&lt;host&gt;:&lt;port&gt;/&lt;context&gt;/editUser.action?id=22&name=John
59   * because the parameter defined in the param tag will take precedence.</p>
60   *
61   * <!-- END SNIPPET: javadoc -->
62   *
63   *
64   * <!-- START SNIPPET: params -->
65   *
66   * <ul>
67   *      <li>action (String) - (value or action choose either one, if both exist value takes precedence) action's name (alias) <li>
68   *      <li>value (String) - (value or action choose either one, if both exist value takes precedence) the url itself</li>
69   *      <li>scheme (String) - http scheme (http, https) defaults to the scheme this request is in</li>
70   *      <li>namespace - action's namespace</li>
71   *      <li>method (String) - action's method name, defaults to 'execute'</li>
72   *      <li>encode (Boolean) - url encode the generated url. Defaults to 'true'.</li>
73   *      <li>includeParams (String) - The includeParams attribute may have the value 'none', 'get' or 'all'. Defaults to 'get'.
74   *                                   none - include no parameters in the URL
75   *                                   get  - include only GET parameters in the URL (default)
76   *                                   all  - include both GET and POST parameters in the URL
77   *      </li>
78   *      <li>includeContext (Boolean) - Specifies whether to include the web app context path. Defaults to 'true'.</li>
79   *      <li>escapeAmp (Boolean) - Specifies whether to escape ampersand (&amp;) to (&amp;amp;) or not. Defaults to 'true'.</li>
80   *      <li>portletMode (String) - The resulting portlet mode.</li>
81   *      <li>windowState (String) - The resulting portlet window state.</li>
82   *      <li>portletUrlType (String) - Specifies if this should be a portlet render or action URL.</li>
83   *      <li>forceAddSchemeHostAndPort (Boolean) - Specifies whether to force the addition of scheme, host and port or not.</li>
84   * </ul>
85   *
86   * <!-- END SNIPPET: params -->
87   *
88   * <p/> <b>Examples</b>
89   * <pre>
90   * <!-- START SNIPPET: example -->
91   *
92   * &lt;-- Example 1 --&gt;
93   * &lt;s:url value="editGadget.action"&gt;
94   *     &lt;s:param name="id" value="%{selected}" /&gt;
95   * &lt;/s:url&gt;
96   *
97   * &lt;-- Example 2 --&gt;
98   * &lt;s:url action="editGadget"&gt;
99   *     &lt;s:param name="id" value="%{selected}" /&gt;
100  * &lt;/s:url&gt;
101  *
102  * &lt;-- Example 3--&gt;
103  * &lt;s:url includeParams="get"&gt;
104  *     &lt;s:param name="id" value="%{'22'}" /&gt;
105  * &lt;/s:url&gt;
106  *
107  * <!-- END SNIPPET: example -->
108  * </pre>
109  *
110  * @see Param
111  *
112  */
113 @StrutsTag(name="url", tldTagClass="org.apache.struts2.views.jsp.URLTag", description="This tag is used to create a URL")
114 public class URL extends ContextBean {
115     private static final Logger LOG = LoggerFactory.getLogger(URL.class);
116     private UrlProvider urlProvider;
117     private UrlRenderer urlRenderer;
118 
119     public URL(ValueStack stack, HttpServletRequest req, HttpServletResponse res) {
120         super(stack);
121         urlProvider = new ComponentUrlProvider(this, this.parameters);
122         urlProvider.setHttpServletRequest(req);
123         urlProvider.setHttpServletResponse(res);
124     }
125 
126     @Inject(StrutsConstants.STRUTS_URL_INCLUDEPARAMS)
127     public void setUrlIncludeParams(String urlIncludeParams) {
128        urlProvider.setUrlIncludeParams(urlIncludeParams);
129     }
130 
131     @Inject
132 	public void setUrlRenderer(UrlRenderer urlRenderer) {
133 		urlProvider.setUrlRenderer(urlRenderer);
134         this.urlRenderer = urlRenderer;
135 	}
136 
137     @Inject(required=false)
138     public void setExtraParameterProvider(ExtraParameterProvider provider) {
139         urlProvider.setExtraParameterProvider(provider);
140     }
141 
142     public boolean start(Writer writer) {
143         boolean result = super.start(writer);
144         urlRenderer.beforeRenderUrl(urlProvider);
145         return result;
146     }
147 
148     public boolean end(Writer writer, String body) {
149     	urlRenderer.renderUrl(writer, urlProvider);
150         return super.end(writer, body);
151     }
152 
153     public String findString(String expr) {
154         return super.findString(expr);
155     }
156 
157     public UrlProvider getUrlProvider() {
158         return urlProvider;
159     }
160 
161     @StrutsTagAttribute(description="The includeParams attribute may have the value 'none', 'get' or 'all'", defaultValue="none")
162     public void setIncludeParams(String includeParams) {
163         urlProvider.setIncludeParams(includeParams);
164     }
165 
166     @StrutsTagAttribute(description="Set scheme attribute")
167     public void setScheme(String scheme) {
168         urlProvider.setScheme(scheme);
169     }
170 
171     @StrutsTagAttribute(description="The target value to use, if not using action")
172     public void setValue(String value) {
173         urlProvider.setValue(value);
174     }
175 
176     @StrutsTagAttribute(description="The action to generate the URL for, if not using value")
177     public void setAction(String action) {
178         urlProvider.setAction(action);
179     }
180 
181     @StrutsTagAttribute(description="The namespace to use")
182     public void setNamespace(String namespace) {
183         urlProvider.setNamespace(namespace);
184     }
185 
186     @StrutsTagAttribute(description="The method of action to use")
187     public void setMethod(String method) {
188         urlProvider.setMethod(method);
189     }
190 
191     @StrutsTagAttribute(description="Whether to encode parameters", type="Boolean", defaultValue="true")
192     public void setEncode(boolean encode) {
193         urlProvider.setEncode(encode);
194     }
195 
196     @StrutsTagAttribute(description="Whether actual context should be included in URL", type="Boolean", defaultValue="true")
197     public void setIncludeContext(boolean includeContext) {
198         urlProvider.setIncludeContext(includeContext);
199     }
200 
201     @StrutsTagAttribute(description="The resulting portlet mode")
202     public void setPortletMode(String portletMode) {
203         urlProvider.setPortletMode(portletMode);
204     }
205 
206     @StrutsTagAttribute(description="The resulting portlet window state")
207     public void setWindowState(String windowState) {
208         urlProvider.setWindowState(windowState);
209     }
210 
211     @StrutsTagAttribute(description="Specifies if this should be a portlet render or action URL. Default is \"render\". To create an action URL, use \"action\".")
212     public void setPortletUrlType(String portletUrlType) {
213        urlProvider.setPortletUrlType(portletUrlType);
214     }
215 
216     @StrutsTagAttribute(description="The anchor for this URL")
217     public void setAnchor(String anchor) {
218         urlProvider.setAnchor(anchor);
219     }
220 
221     @StrutsTagAttribute(description="Specifies whether to escape ampersand (&amp;) to (&amp;amp;) or not", type="Boolean", defaultValue="true")
222     public void setEscapeAmp(boolean escapeAmp) {
223         urlProvider.setEscapeAmp(escapeAmp);
224     }
225 
226     @StrutsTagAttribute(description="Specifies whether to force the addition of scheme, host and port or not", type="Boolean", defaultValue="false")
227     public void setForceAddSchemeHostAndPort(boolean forceAddSchemeHostAndPort) {
228         urlProvider.setForceAddSchemeHostAndPort(forceAddSchemeHostAndPort);
229     }
230 }