001: package org.apache.turbine.services.pull.tools;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import org.apache.commons.configuration.Configuration;
023:
024: import org.apache.commons.logging.Log;
025: import org.apache.commons.logging.LogFactory;
026:
027: import org.apache.turbine.Turbine;
028: import org.apache.turbine.TurbineConstants;
029: import org.apache.turbine.services.pull.ApplicationTool;
030: import org.apache.turbine.util.RunData;
031: import org.apache.turbine.util.parser.ParameterParser;
032: import org.apache.turbine.util.uri.TemplateURI;
033:
034: /**
035: * This is a pull to to be used in Templates to convert links in
036: * Templates into the correct references.
037: *
038: * The pull service might insert this tool into the Context.
039: * in templates. Here's an example of its Velocity use:
040: *
041: * <p><code>
042: * $link.setPage("index.vm").addPathInfo("hello","world")
043: * This would return: http://foo.com/Turbine/template/index.vm/hello/world
044: * </code>
045: *
046: * <p>
047: *
048: * This is an application pull tool for the template system. You should <b>not</b>
049: * use it in a normal application!
050: *
051: * @author <a href="mbryson@mont.mindspring.com">Dave Bryson</a>
052: * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
053: * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
054: * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
055: * @version $Id: TemplateLink.java 544066 2007-06-04 06:21:13Z hoffmann $
056: */
057:
058: public class TemplateLink implements ApplicationTool {
059: /** Prefix for Parameters for this tool */
060: public static final String TEMPLATE_LINK_PREFIX = "tool.link";
061:
062: /** Should this tool return relative URIs or absolute? Default: Absolute. */
063: public static final String TEMPLATE_LINK_RELATIVE_KEY = "want.relative";
064:
065: /** Default Value for TEMPLATE_LINK_RELATIVE_KEY */
066: public static final boolean TEMPLATE_LINK_RELATIVE_DEFAULT = false;
067:
068: /** Do we want a relative link? */
069: boolean wantRelative = false;
070:
071: /** cache of the template name for getPage() */
072: private String template = null;
073:
074: /** TemplateURI used as backend for this object */
075: protected TemplateURI templateURI = null;
076:
077: /** Logging */
078: private static Log log = LogFactory.getLog(TemplateLink.class);
079:
080: /**
081: * Default constructor
082: * <p>
083: * The init method must be called before use.
084: */
085: public TemplateLink() {
086: }
087:
088: /*
089: * ========================================================================
090: *
091: * Application Tool Interface
092: *
093: * ========================================================================
094: *
095: */
096:
097: /**
098: * This will initialise a TemplateLink object that was
099: * 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: // we just blithely cast to RunData as if another object
106: // or null is passed in we'll throw an appropriate runtime
107: // exception.
108:
109: templateURI = new TemplateURI((RunData) data);
110:
111: Configuration conf = Turbine.getConfiguration().subset(
112: TEMPLATE_LINK_PREFIX);
113:
114: if (conf != null) {
115: wantRelative = conf.getBoolean(TEMPLATE_LINK_RELATIVE_KEY,
116: TEMPLATE_LINK_RELATIVE_DEFAULT);
117: }
118:
119: }
120:
121: /**
122: * Refresh method - does nothing
123: */
124: public void refresh() {
125: // empty
126: }
127:
128: /*
129: * ========================================================================
130: *
131: * getter/setter
132: *
133: * All setter return "this" so you can "chain" them together in the Context
134: *
135: * ========================================================================
136: */
137:
138: /**
139: * This will turn off the execution of res.encodeURL()
140: * by making res == null. This is a hack for cases
141: * where you don't want to see the session information
142: *
143: * @return A <code>TemplateLink</code> (self).
144: */
145: public TemplateLink setEncodeURLOff() {
146: templateURI.clearResponse();
147: return this ;
148: }
149:
150: /**
151: * Sets the template variable used by the Template Service.
152: *
153: * @param template A String with the template name.
154: * @return A TemplateLink.
155: */
156: public TemplateLink setPage(String template) {
157: log.debug("setPage(" + template + ")");
158: this .template = template;
159: templateURI.setTemplate(template);
160: return this ;
161: }
162:
163: /**
164: * Gets the template variable used by the Template Service.
165: * It is only available after setPage() has been called.
166: *
167: * @return The template name.
168: */
169: public String getPage() {
170: return template;
171: }
172:
173: /**
174: * Sets the action= value for this URL.
175: *
176: * By default it adds the information to the path_info instead
177: * of the query data.
178: *
179: * @param action A String with the action value.
180: * @return A <code>TemplateLink</code> (self).
181: */
182: public TemplateLink setAction(String action) {
183: log.debug("setAction(" + action + ")");
184: templateURI.setAction(action);
185: return this ;
186: }
187:
188: /**
189: * Sets the action= and eventSubmit= values for this URL.
190: *
191: * By default it adds the information to the path_info instead
192: * of the query data.
193: *
194: * @param action A String with the action value.
195: * @param event A string with the event name.
196: * @return A <code>TemplateLink</code> (self).
197: */
198: public TemplateLink setActionEvent(String action, String event) {
199: log.debug("setActionEvent(" + action + ", " + event + ")");
200: templateURI.setActionEvent(action, event);
201: return this ;
202: }
203:
204: /**
205: * Sets the eventSubmit_= value for this URL.
206: *
207: * By default it adds the information to the path_info instead
208: * of the query data.
209: *
210: * @param action A String with the event value.
211: * @return A <code>TemplateLink</code> (self).
212: */
213: public TemplateLink setEvent(String action) {
214: log.debug("setEvent(" + action + ")");
215: templateURI.setEvent(action);
216: return this ;
217: }
218:
219: /**
220: * Sets the screen= value for this URL.
221: *
222: * By default it adds the information to the path_info instead
223: * of the query data.
224: *
225: * @param screen A String with the screen value.
226: * @return A <code>TemplateLink</code> (self).
227: */
228: public TemplateLink setScreen(String screen) {
229: log.debug("setScreen(" + screen + ")");
230: templateURI.setScreen(screen);
231: return this ;
232: }
233:
234: /**
235: * Sets a reference anchor (#ref).
236: *
237: * @param reference A String containing the reference.
238: * @return A <code>TemplateLink</code> (self).
239: */
240: public TemplateLink setReference(String reference) {
241: templateURI.setReference(reference);
242: return this ;
243: }
244:
245: /**
246: * Returns the current reference anchor.
247: *
248: * @return A String containing the reference.
249: */
250: public String getReference() {
251: return templateURI.getReference();
252: }
253:
254: /*
255: * ========================================================================
256: *
257: * Adding and removing Data from the Path Info and Query Data
258: *
259: * ========================================================================
260: */
261:
262: /**
263: * Adds a name=value pair for every entry in a ParameterParser
264: * object to the path_info string.
265: *
266: * @param pp A ParameterParser.
267: * @return A <code>TemplateLink</code> (self).
268: */
269: public TemplateLink addPathInfo(ParameterParser pp) {
270: templateURI.addPathInfo(pp);
271: return this ;
272: }
273:
274: /**
275: * Adds a name=value pair to the path_info string.
276: *
277: * @param name A String with the name to add.
278: * @param value An Object with the value to add.
279: * @return A <code>TemplateLink</code> (self).
280: */
281: public TemplateLink addPathInfo(String name, Object value) {
282: templateURI.addPathInfo(name, value);
283: return this ;
284: }
285:
286: /**
287: * Adds a name=value pair to the path_info string.
288: *
289: * @param name A String with the name to add.
290: * @param value A String with the value to add.
291: * @return A <code>TemplateLink</code> (self).
292: */
293: public TemplateLink addPathInfo(String name, String value) {
294: templateURI.addPathInfo(name, value);
295: return this ;
296: }
297:
298: /**
299: * Adds a name=value pair to the path_info string.
300: *
301: * @param name A String with the name to add.
302: * @param value A double with the value to add.
303: * @return A <code>TemplateLink</code> (self).
304: */
305: public TemplateLink addPathInfo(String name, double value) {
306: templateURI.addPathInfo(name, value);
307: return this ;
308: }
309:
310: /**
311: * Adds a name=value pair to the path_info string.
312: *
313: * @param name A String with the name to add.
314: * @param value An int with the value to add.
315: * @return A <code>TemplateLink</code> (self).
316: */
317: public TemplateLink addPathInfo(String name, int value) {
318: templateURI.addPathInfo(name, value);
319: return this ;
320: }
321:
322: /**
323: * Adds a name=value pair to the path_info string.
324: *
325: * @param name A String with the name to add.
326: * @param value A long with the value to add.
327: * @return A <code>TemplateLink</code> (self).
328: */
329: public TemplateLink addPathInfo(String name, long value) {
330: templateURI.addPathInfo(name, value);
331: return this ;
332: }
333:
334: /**
335: * Adds a name=value pair to the query string.
336: *
337: * @param name A String with the name to add.
338: * @param value An Object with the value to add.
339: * @return A <code>TemplateLink</code> (self).
340: */
341: public TemplateLink addQueryData(String name, Object value) {
342: templateURI.addQueryData(name, value);
343: return this ;
344: }
345:
346: /**
347: * Adds a name=value pair to the query string.
348: *
349: * @param name A String with the name to add.
350: * @param value A String with the value to add.
351: * @return A <code>TemplateLink</code> (self).
352: */
353: public TemplateLink addQueryData(String name, String value) {
354: templateURI.addQueryData(name, value);
355: return this ;
356: }
357:
358: /**
359: * Adds a name=value pair to the query string.
360: *
361: * @param name A String with the name to add.
362: * @param value A double with the value to add.
363: * @return A <code>TemplateLink</code> (self).
364: */
365: public TemplateLink addQueryData(String name, double value) {
366: templateURI.addQueryData(name, value);
367: return this ;
368: }
369:
370: /**
371: * Adds a name=value pair to the query string.
372: *
373: * @param name A String with the name to add.
374: * @param value An int with the value to add.
375: * @return A <code>TemplateLink</code> (self).
376: */
377: public TemplateLink addQueryData(String name, int value) {
378: templateURI.addQueryData(name, value);
379: return this ;
380: }
381:
382: /**
383: * Adds a name=value pair to the query string.
384: *
385: * @param name A String with the name to add.
386: * @param value A long with the value to add.
387: * @return A <code>TemplateLink</code> (self).
388: */
389: public TemplateLink addQueryData(String name, long value) {
390: templateURI.addQueryData(name, value);
391: return this ;
392: }
393:
394: /**
395: * Adds a name=value pair for every entry in a ParameterParser
396: * object to the query string.
397: *
398: * @param pp A ParameterParser.
399: * @return A <code>TemplateLink</code> (self).
400: */
401: public TemplateLink addQueryData(ParameterParser pp) {
402: templateURI.addQueryData(pp);
403: return this ;
404: }
405:
406: /**
407: * Removes all the path info elements.
408: *
409: * @return A <code>TemplateLink</code> (self).
410: */
411: public TemplateLink removePathInfo() {
412: templateURI.removePathInfo();
413: return this ;
414: }
415:
416: /**
417: * Removes a name=value pair from the path info.
418: *
419: * @param name A String with the name to be removed.
420: * @return A <code>TemplateLink</code> (self).
421: */
422: public TemplateLink removePathInfo(String name) {
423: templateURI.removePathInfo(name);
424: return this ;
425: }
426:
427: /**
428: * Removes all the query string elements.
429: *
430: * @return A <code>TemplateLink</code> (self).
431: */
432: public TemplateLink removeQueryData() {
433: templateURI.removeQueryData();
434: return this ;
435: }
436:
437: /**
438: * Removes a name=value pair from the query string.
439: *
440: * @param name A String with the name to be removed.
441: * @return A <code>TemplateLink</code> (self).
442: */
443: public TemplateLink removeQueryData(String name) {
444: templateURI.removeQueryData(name);
445: return this ;
446: }
447:
448: /**
449: * Builds the URL with all of the data URL-encoded as well as
450: * encoded using HttpServletResponse.encodeUrl(). The resulting
451: * URL is absolute; it starts with http/https...
452: *
453: * <p>
454: * <code><pre>
455: * TemplateURI tui = new TemplateURI (data, "UserScreen");
456: * tui.addPathInfo("user","jon");
457: * tui.getAbsoluteLink();
458: * </pre></code>
459: *
460: * The above call to absoluteLink() would return the String:
461: *
462: * <p>
463: * http://www.server.com/servlets/Turbine/screen/UserScreen/user/jon
464: *
465: * <p>
466: * After rendering the URI, it clears the
467: * pathInfo and QueryString portions of the TemplateURI. So you can
468: * use the $link reference multiple times on a page and start over
469: * with a fresh object every time.
470: *
471: * @return A String with the built URL.
472: */
473: public String getAbsoluteLink() {
474: String output = templateURI.getAbsoluteLink();
475:
476: // This was added to use $link multiple times on a page and start
477: // over with a fresh set of data every time.
478: templateURI.removePathInfo();
479: templateURI.removeQueryData();
480:
481: return output;
482: }
483:
484: /**
485: * Builds the URL with all of the data URL-encoded as well as
486: * encoded using HttpServletResponse.encodeUrl(). The resulting
487: * URL is relative to the webserver root.
488: *
489: * <p>
490: * <code><pre>
491: * TemplateURI tui = new TemplateURI (data, "UserScreen");
492: * tui.addPathInfo("user","jon");
493: * tui.getRelativeLink();
494: * </pre></code>
495: *
496: * The above call to absoluteLink() would return the String:
497: *
498: * <p>
499: * /servlets/Turbine/screen/UserScreen/user/jon
500: *
501: * <p>
502: * After rendering the URI, it clears the
503: * pathInfo and QueryString portions of the TemplateURI. So you can
504: * use the $link reference multiple times on a page and start over
505: * with a fresh object every time.
506: *
507: * @return A String with the built URL.
508: */
509: public String getRelativeLink() {
510: String output = templateURI.getRelativeLink();
511:
512: // This was added to use $link multiple times on a page and start
513: // over with a fresh set of data every time.
514: templateURI.removePathInfo();
515: templateURI.removeQueryData();
516:
517: return output;
518: }
519:
520: /**
521: * Returns the URI. After rendering the URI, it clears the
522: * pathInfo and QueryString portions of the TemplateURI.
523: *
524: * @return A String with the URI in the form
525: * http://foo.com/Turbine/template/index.wm/hello/world
526: */
527: public String getLink() {
528: return wantRelative ? getRelativeLink() : getAbsoluteLink();
529: }
530:
531: /**
532: * Returns the relative URI leaving the source intact. Use this
533: * if you need the path_info and query data multiple times.
534: * This is equivalent to $link.Link or just $link,
535: * but does not reset the path_info and query data.
536: *
537: * @return A String with the URI in the form
538: * http://foo.com/Turbine/template/index.wm/hello/world
539: */
540: public String getURI() {
541: return wantRelative ? templateURI.getRelativeLink()
542: : templateURI.getAbsoluteLink();
543: }
544:
545: /**
546: * Returns the absolute URI leaving the source intact. Use this
547: * if you need the path_info and query data multiple times.
548: * This is equivalent to $link.AbsoluteLink but does not reset
549: * the path_info and query data.
550: *
551: * @return A String with the URI in the form
552: * http://foo.com/Turbine/template/index.wm/hello/world
553: */
554: public String getAbsoluteURI() {
555: return templateURI.getAbsoluteLink();
556: }
557:
558: /**
559: * Returns the relative URI leaving the source intact. Use this
560: * if you need the path_info and query data multiple times.
561: * This is equivalent to $link.RelativeLink but does not reset
562: * the path_info and query data.
563: *
564: * @return A String with the URI in the form
565: * http://foo.com/Turbine/template/index.wm/hello/world
566: */
567: public String getRelativeURI() {
568: return templateURI.getRelativeLink();
569: }
570:
571: /**
572: * Same as getLink().
573: *
574: * @return A String with the URI represented by this object.
575: *
576: */
577: public String toString() {
578: return getLink();
579: }
580: }
|