Java > Open Source Codes > org > apache > turbine > services > pull > tools > TemplateLink


1 package org.apache.turbine.services.pull.tools;
2
3 /*
4  * Copyright 2001-2004 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,v 1.8.2.3 2004/10/08 12:31:43 henning Exp $
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 }
619

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags