1 package org.apache.turbine.services.pull.tools;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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
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
107
108
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
129 }
130
131
132
133
134
135
136
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
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
507
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
545
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 }