View Javadoc

1   package org.apache.turbine.services.pull.tools;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * 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, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  import org.apache.commons.configuration.Configuration;
20  
21  import org.apache.commons.logging.Log;
22  import org.apache.commons.logging.LogFactory;
23  
24  import org.apache.turbine.Turbine;
25  import org.apache.turbine.services.pull.ApplicationTool;
26  import org.apache.turbine.util.RunData;
27  import org.apache.turbine.util.parser.ParameterParser;
28  import org.apache.turbine.util.uri.TemplateURI;
29  
30  /***
31   * This is a pull to to be used in Templates to convert links in
32   * Templates into the correct references.
33   *
34   * The pull service might insert this tool into the Context.
35   * in templates.  Here's an example of its Velocity use:
36   *
37   * <p><code>
38   * $link.setPage("index.vm").addPathInfo("hello","world")
39   * This would return: http://foo.com/Turbine/template/index.vm/hello/world
40   * </code>
41   *
42   * <p>
43   *
44   * This is an application pull tool for the template system. You should <b>not</b>
45   * use it in a normal application!
46   *
47   * @author <a href="mbryson@mont.mindspring.com">Dave Bryson</a>
48   * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
49   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
50   * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
51   * @version $Id: TemplateLink.java 264148 2005-08-29 14:21:04Z henning $
52   */
53  
54  public class TemplateLink
55      implements ApplicationTool
56  {
57      /*** Prefix for Parameters for this tool */
58      public static final String TEMPLATE_LINK_PREFIX = "tool.link";
59  
60      /*** Should this tool return relative URIs or absolute? Default: Absolute. */
61      public static final String TEMPLATE_LINK_RELATIVE_KEY = "want.relative";
62  
63      /*** Default Value for TEMPLATE_LINK_RELATIVE_KEY */
64      public static final boolean TEMPLATE_LINK_RELATIVE_DEFAULT = false;
65  
66  
67      /*** Do we want a relative link? */
68      boolean wantRelative = false;
69  
70      /*** cache of the template name for getPage() */
71      private String template = null;
72  
73      /*** TemplateURI used as backend for this object */
74      private TemplateURI templateURI = null;
75  
76      /*** Logging */
77      private static Log log = LogFactory.getLog(TemplateLink.class);
78  
79      /***
80       * Default constructor
81       * <p>
82       * The init method must be called before use.
83       */
84      public TemplateLink()
85      {
86      }
87  
88      /*
89       * ========================================================================
90       *
91       * Application Tool Interface
92       *
93       * ========================================================================
94       *
95       */
96  
97      /***
98       * This will initialise a TemplateLink object that was
99       * constructed with the default constructor (ApplicationTool
100      * method).
101      *
102      * @param data assumed to be a RunData object
103      */
104     public void init(Object data)
105     {
106         // we just blithely cast to RunData as if another object
107         // or null is passed in we'll throw an appropriate runtime
108         // exception.
109 
110         templateURI = new TemplateURI((RunData) data);
111 
112         Configuration conf =
113                 Turbine.getConfiguration().subset(TEMPLATE_LINK_PREFIX);
114 
115         if (conf != null)
116         {
117             wantRelative = conf.getBoolean(TEMPLATE_LINK_RELATIVE_KEY,
118                     TEMPLATE_LINK_RELATIVE_DEFAULT);
119         }
120 
121     }
122 
123     /***
124      * Refresh method - does nothing
125      */
126     public void refresh()
127     {
128         // empty
129     }
130 
131     /*
132      * ========================================================================
133      *
134      * getter/setter
135      *
136      * All setter return "this" so you can "chain" them together in the Context
137      *
138      * ========================================================================
139      */
140 
141     /***
142      * This will turn off the execution of res.encodeURL()
143      * by making res == null. This is a hack for cases
144      * where you don't want to see the session information
145      *
146      * @return A <code>TemplateLink</code> (self).
147      */
148     public TemplateLink setEncodeURLOff()
149     {
150         templateURI.clearResponse();
151         return this;
152     }
153 
154     /***
155      * Sets the template variable used by the Template Service.
156      *
157      * @param template A String with the template name.
158      * @return A TemplateLink.
159      */
160     public TemplateLink setPage(String template)
161     {
162         log.debug("setPage(" + template + ")");
163         this.template = template;
164         templateURI.setTemplate(template);
165         return this;
166     }
167 
168     /***
169      * Gets the template variable used by the Template Service.
170      * It is only available after setPage() has been called.
171      *
172      * @return The template name.
173      */
174     public String getPage()
175     {
176         return template;
177     }
178 
179     /***
180      * Sets the action= value for this URL.
181      *
182      * By default it adds the information to the path_info instead
183      * of the query data.
184      *
185      * @param action A String with the action value.
186      * @return A <code>TemplateLink</code> (self).
187      */
188     public TemplateLink setAction(String action)
189     {
190         log.debug("setAction(" + action + ")");
191         templateURI.setAction(action);
192         return this;
193     }
194 
195     /***
196      * Sets the action= and eventSubmit= values for this URL.
197      *
198      * By default it adds the information to the path_info instead
199      * of the query data.
200      *
201      * @param action A String with the action value.
202      * @param event A string with the event name.
203      * @return A <code>TemplateLink</code> (self).
204      */
205     public TemplateLink setActionEvent(String action, String event)
206     {
207         log.debug("setActionEvent(" + action + ", "+ event +")");
208         templateURI.setActionEvent(action, event);
209         return this;
210     }
211 
212     /***
213      * Sets the eventSubmit_= value for this URL.
214      *
215      * By default it adds the information to the path_info instead
216      * of the query data.
217      *
218      * @param action A String with the event value.
219      * @return A <code>TemplateLink</code> (self).
220      */
221     public TemplateLink setEvent(String action)
222     {
223         log.debug("setEvent(" + action + ")");
224         templateURI.setEvent(action);
225         return this;
226     }
227 
228     /***
229      * Sets the screen= value for this URL.
230      *
231      * By default it adds the information to the path_info instead
232      * of the query data.
233      *
234      * @param screen A String with the screen value.
235      * @return A <code>TemplateLink</code> (self).
236      */
237     public TemplateLink setScreen(String screen)
238     {
239         log.debug("setScreen(" + screen + ")");
240         templateURI.setScreen(screen);
241         return this;
242     }
243 
244     /***
245      * Sets a reference anchor (#ref).
246      *
247      * @param reference A String containing the reference.
248      * @return A <code>TemplateLink</code> (self).
249      */
250     public TemplateLink setReference(String reference)
251     {
252         templateURI.setReference(reference);
253         return this;
254     }
255 
256     /***
257      * Returns the current reference anchor.
258      *
259      * @return A String containing the reference.
260      */
261     public String getReference()
262     {
263         return templateURI.getReference();
264     }
265 
266     /*
267      * ========================================================================
268      *
269      * Adding and removing Data from the Path Info and Query Data
270      *
271      * ========================================================================
272      */
273 
274 
275     /***
276      * Adds a name=value pair for every entry in a ParameterParser
277      * object to the path_info string.
278      *
279      * @param pp A ParameterParser.
280      * @return A <code>TemplateLink</code> (self).
281      */
282     public TemplateLink addPathInfo(ParameterParser pp)
283     {
284         templateURI.addPathInfo(pp);
285         return this;
286     }
287 
288     /***
289      * Adds a name=value pair to the path_info string.
290      *
291      * @param name A String with the name to add.
292      * @param value An Object with the value to add.
293      * @return A <code>TemplateLink</code> (self).
294      */
295     public TemplateLink addPathInfo(String name, Object value)
296     {
297         templateURI.addPathInfo(name, value);
298         return this;
299     }
300 
301     /***
302      * Adds a name=value pair to the path_info string.
303      *
304      * @param name A String with the name to add.
305      * @param value A String with the value to add.
306      * @return A <code>TemplateLink</code> (self).
307      */
308     public TemplateLink addPathInfo(String name, String value)
309     {
310         templateURI.addPathInfo(name, value);
311         return this;
312     }
313 
314     /***
315      * Adds a name=value pair to the path_info string.
316      *
317      * @param name A String with the name to add.
318      * @param value A double with the value to add.
319      * @return A <code>TemplateLink</code> (self).
320      */
321     public TemplateLink addPathInfo(String name, double value)
322     {
323         templateURI.addPathInfo(name, value);
324         return this;
325     }
326 
327     /***
328      * Adds a name=value pair to the path_info string.
329      *
330      * @param name A String with the name to add.
331      * @param value An int with the value to add.
332      * @return A <code>TemplateLink</code> (self).
333      */
334     public TemplateLink addPathInfo(String name, int value)
335     {
336         templateURI.addPathInfo(name, value);
337         return this;
338     }
339 
340     /***
341      * Adds a name=value pair to the path_info string.
342      *
343      * @param name A String with the name to add.
344      * @param value A long with the value to add.
345      * @return A <code>TemplateLink</code> (self).
346      */
347     public TemplateLink addPathInfo(String name, long value)
348     {
349         templateURI.addPathInfo(name, value);
350         return this;
351     }
352 
353     /***
354      * Adds a name=value pair to the query string.
355      *
356      * @param name A String with the name to add.
357      * @param value An Object with the value to add.
358      * @return A <code>TemplateLink</code> (self).
359      */
360     public TemplateLink addQueryData(String name, Object value)
361     {
362         templateURI.addQueryData(name, value);
363         return this;
364     }
365 
366     /***
367      * Adds a name=value pair to the query string.
368      *
369      * @param name A String with the name to add.
370      * @param value A String with the value to add.
371      * @return A <code>TemplateLink</code> (self).
372      */
373     public TemplateLink addQueryData(String name, String value)
374     {
375         templateURI.addQueryData(name, value);
376         return this;
377     }
378 
379     /***
380      * Adds a name=value pair to the query string.
381      *
382      * @param name A String with the name to add.
383      * @param value A double with the value to add.
384      * @return A <code>TemplateLink</code> (self).
385      */
386     public TemplateLink addQueryData(String name, double value)
387     {
388         templateURI.addQueryData(name, value);
389         return this;
390     }
391 
392     /***
393      * Adds a name=value pair to the query string.
394      *
395      * @param name A String with the name to add.
396      * @param value An int with the value to add.
397      * @return A <code>TemplateLink</code> (self).
398      */
399     public TemplateLink addQueryData(String name, int value)
400     {
401         templateURI.addQueryData(name, value);
402         return this;
403     }
404 
405     /***
406      * Adds a name=value pair to the query string.
407      *
408      * @param name A String with the name to add.
409      * @param value A long with the value to add.
410      * @return A <code>TemplateLink</code> (self).
411      */
412     public TemplateLink addQueryData(String name, long value)
413     {
414         templateURI.addQueryData(name, value);
415         return this;
416     }
417 
418     /***
419      * Adds a name=value pair for every entry in a ParameterParser
420      * object to the query string.
421      *
422      * @param pp A ParameterParser.
423      * @return A <code>TemplateLink</code> (self).
424      */
425     public TemplateLink addQueryData(ParameterParser pp)
426     {
427         templateURI.addQueryData(pp);
428         return this;
429     }
430 
431     /***
432      * Removes all the path info elements.
433      *
434      * @return A <code>TemplateLink</code> (self).
435      */
436     public TemplateLink removePathInfo()
437     {
438         templateURI.removePathInfo();
439         return this;
440     }
441 
442     /***
443      * Removes a name=value pair from the path info.
444      *
445      * @param name A String with the name to be removed.
446      * @return A <code>TemplateLink</code> (self).
447      */
448     public TemplateLink removePathInfo(String name)
449     {
450         templateURI.removePathInfo(name);
451         return this;
452     }
453 
454     /***
455      * Removes all the query string elements.
456      *
457      * @return A <code>TemplateLink</code> (self).
458      */
459     public TemplateLink removeQueryData()
460     {
461         templateURI.removeQueryData();
462         return this;
463     }
464 
465     /***
466      * Removes a name=value pair from the query string.
467      *
468      * @param name A String with the name to be removed.
469      * @return A <code>TemplateLink</code> (self).
470      */
471     public TemplateLink removeQueryData(String name)
472     {
473         templateURI.removeQueryData(name);
474         return this;
475     }
476 
477     /***
478      * Builds the URL with all of the data URL-encoded as well as
479      * encoded using HttpServletResponse.encodeUrl(). The resulting
480      * URL is absolute; it starts with http/https...
481      *
482      * <p>
483      * <code><pre>
484      * TemplateURI tui = new TemplateURI (data, "UserScreen");
485      * tui.addPathInfo("user","jon");
486      * tui.getAbsoluteLink();
487      * </pre></code>
488      *
489      *  The above call to absoluteLink() would return the String:
490      *
491      * <p>
492      * http://www.server.com/servlets/Turbine/screen/UserScreen/user/jon
493      *
494      * <p>
495      * After rendering the URI, it clears the
496      * pathInfo and QueryString portions of the TemplateURI. So you can
497      * use the $link reference multiple times on a page and start over
498      * with a fresh object every time.
499      *
500      * @return A String with the built URL.
501      */
502     public String getAbsoluteLink()
503     {
504         String output = templateURI.getAbsoluteLink();
505 
506         // This was added to use $link multiple times on a page and start
507         // over with a fresh set of data every time.
508         templateURI.removePathInfo();
509         templateURI.removeQueryData();
510 
511         return output;
512     }
513 
514 
515     /***
516      * Builds the URL with all of the data URL-encoded as well as
517      * encoded using HttpServletResponse.encodeUrl(). The resulting
518      * URL is relative to the webserver root.
519      *
520      * <p>
521      * <code><pre>
522      * TemplateURI tui = new TemplateURI (data, "UserScreen");
523      * tui.addPathInfo("user","jon");
524      * tui.getRelativeLink();
525      * </pre></code>
526      *
527      *  The above call to absoluteLink() would return the String:
528      *
529      * <p>
530      * /servlets/Turbine/screen/UserScreen/user/jon
531      *
532      * <p>
533      * After rendering the URI, it clears the
534      * pathInfo and QueryString portions of the TemplateURI. So you can
535      * use the $link reference multiple times on a page and start over
536      * with a fresh object every time.
537      *
538      * @return A String with the built URL.
539      */
540     public String getRelativeLink()
541     {
542         String output = templateURI.getRelativeLink();
543 
544         // This was added to use $link multiple times on a page and start
545         // over with a fresh set of data every time.
546         templateURI.removePathInfo();
547         templateURI.removeQueryData();
548 
549         return output;
550     }
551 
552     /***
553      * Returns the URI. After rendering the URI, it clears the
554      * pathInfo and QueryString portions of the TemplateURI.
555      *
556      * @return A String with the URI in the form
557      * http://foo.com/Turbine/template/index.wm/hello/world
558      */
559     public String getLink()
560     {
561         return wantRelative ?
562                 getRelativeLink() : getAbsoluteLink();
563     }
564 
565     /***
566      * Returns the relative URI leaving the source intact. Use this
567      * if you need the path_info and query data multiple times.
568      * This is equivalent to $link.Link or just $link,
569      * but does not reset the path_info and query data.
570      *
571      * @return A String with the URI in the form
572      * http://foo.com/Turbine/template/index.wm/hello/world
573      */
574     public String getURI()
575     {
576         return wantRelative ?
577                 templateURI.getRelativeLink() : templateURI.getAbsoluteLink();
578     }
579 
580     /***
581      * Returns the absolute URI leaving the source intact. Use this
582      * if you need the path_info and query data multiple times.
583      * This is equivalent to $link.AbsoluteLink but does not reset
584      * the path_info and query data.
585      *
586      * @return A String with the URI in the form
587      * http://foo.com/Turbine/template/index.wm/hello/world
588      */
589     public String getAbsoluteURI()
590     {
591         return templateURI.getAbsoluteLink();
592     }
593 
594     /***
595      * Returns the relative URI leaving the source intact. Use this
596      * if you need the path_info and query data multiple times.
597      * This is equivalent to $link.RelativeLink but does not reset
598      * the path_info and query data.
599      *
600      * @return A String with the URI in the form
601      * http://foo.com/Turbine/template/index.wm/hello/world
602      */
603     public String getRelativeURI()
604     {
605         return templateURI.getRelativeLink();
606     }
607 
608     /***
609      * Same as getLink().
610      *
611      * @return A String with the URI represented by this object.
612      *
613      */
614     public String toString()
615     {
616         return getLink();
617     }
618 }