View Javadoc

1   package org.apache.turbine.util.template;
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.turbine.services.pull.ApplicationTool;
20  import org.apache.turbine.util.DynamicURI;
21  import org.apache.turbine.util.RunData;
22  import org.apache.turbine.util.ServerData;
23  
24  /***
25   * A customized version of the DynamicURI to be used in Templates.
26   * This is automatically inserted into the template context by the
27   * appropriate templating service so page authors can create links
28   * in templates.  Here's an example of its Velocity/WebMacro use:
29   *
30   * <p><code>
31   * $link.setPage("index.wm").addPathInfo("hello","world")
32   * </code><br />This would return: <code>http://foo.com/Turbine/template/index.wm/hello/world
33   * </code>
34   *
35   * @author <a href="mbryson@mont.mindspring.com">Dave Bryson</a>
36   * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
37   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
38   * @version $Id: TemplateLink.java 264152 2005-08-29 14:50:22Z henning $
39   * @deprecated Use {@link org.apache.turbine.services.pull.tools.TemplateLink} for tool usage
40   * and {@link org.apache.turbine.util.uri.TemplateURI} for code usage instead.
41   */
42  public class TemplateLink
43          extends DynamicURI
44          implements ApplicationTool
45  {
46      /*** the pathinfo key stored in the DynamicURI */
47      private static final String TEMPLATE_KEY = "template";
48  
49      /*** cache of the template name for getPage() */
50      private String template = null;
51  
52      /***
53       * Default constructor.
54       * <p>
55       * The init method must be called before use.
56       */
57      public TemplateLink()
58      {
59      }
60  
61      /***
62       * Constructor.
63       *
64       * @param data a Turbine RunData object.
65       */
66      public TemplateLink(RunData data)
67      {
68          super(data);
69      }
70  
71      /***
72       * Constructor.
73       *
74       * @param data a Turbine ServerData object.
75       */
76      public TemplateLink(ServerData data)
77      {
78          super(data);
79      }
80  
81      /***
82       * This will initialize a TemplateLink object that was
83       * constructed with the default constructor (ApplicationTool
84       * method).
85       *
86       * @param data assumed to be a RunData object
87       */
88      public void init(Object data)
89      {
90          if (!(data instanceof RunData) || data == null)
91          {
92              throw new IllegalArgumentException(
93                      "Argument must be an instance of RunData");
94          }
95          super.init((RunData) data);
96      }
97  
98      /***
99       * Refresh method - does nothing
100      */
101     public void refresh()
102     {
103         // empty
104     }
105 
106     /***
107      * This will turn off the execution of res.encodeURL()
108      * by making res == null. This is a hack for cases
109      * where you don't want to see the session information
110      *
111      * @return instance of TemplateLink
112      */
113     public TemplateLink setEncodeURLOff()
114     {
115         this.res = null;
116         return this;
117     }
118 
119     /***
120      * Sets the template variable used by the Template Service.
121      *
122      * @param template A String with the template name.
123      * @return A TemplateLink.
124      */
125     public TemplateLink setPage(String template)
126     {
127         this.template = template;
128         addPathInfo(TEMPLATE_KEY, template);
129         return this;
130     }
131 
132     /***
133      * Gets the template variable used by the Template Service.
134      * It is only available after setPage() has been called.
135      *
136      * @return The template name.
137      */
138     public String getPage()
139     {
140         return template;
141     }
142 
143     /***
144      * Returns the URI. After rendering the URI, it clears the
145      * pathInfo and QueryString portions of the DynamicURI.
146      *
147      * @return A String with the URI in the form
148      * http://foo.com/Turbine/template/index.wm/hello/world
149      */
150     public String toString()
151     {
152         assertInitialized();
153         String output = super.toString();
154 
155         // This was added to allow multilple $link variables in one
156         // template.
157         removePathInfo();
158         removeQueryData();
159 
160         return output;
161     }
162 
163     /***
164      * Returns the URI leaving the source intact. Wraps directly to the
165      * <code>DynamicURI.toString</code> method of the superclass
166      * (avoiding the local toString implementation).
167      *
168      * @return A String with the URI in the form
169      * http://foo.com/Turbine/template/index.wm/hello/world
170      */
171     public String getURI()
172     {
173         return super.toString();
174     }
175 }