Module


1   package org.apache.turbine.modules;
2   
3   /* ====================================================================
4    * The Apache Software License, Version 1.1
5    *
6    * Copyright (c) 2001 The Apache Software Foundation.  All rights
7    * reserved.
8    *
9    * Redistribution and use in source and binary forms, with or without
10   * modification, are permitted provided that the following conditions
11   * are met:
12   *
13   * 1. Redistributions of source code must retain the above copyright
14   *    notice, this list of conditions and the following disclaimer.
15   *
16   * 2. Redistributions in binary form must reproduce the above copyright
17   *    notice, this list of conditions and the following disclaimer in
18   *    the documentation and/or other materials provided with the
19   *    distribution.
20   *
21   * 3. The end-user documentation included with the redistribution,
22   *    if any, must include the following acknowledgment:
23   *       "This product includes software developed by the
24   *        Apache Software Foundation (http://www.apache.org/)."
25   *    Alternately, this acknowledgment may appear in the software itself,
26   *    if and wherever such third-party acknowledgments normally appear.
27   *
28   * 4. The names "Apache" and "Apache Software Foundation" and
29   *    "Apache Turbine" must not be used to endorse or promote products
30   *    derived from this software without prior written permission. For
31   *    written permission, please contact apache@apache.org.
32   *
33   * 5. Products derived from this software may not be called "Apache",
34   *    "Apache Turbine", nor may "Apache" appear in their name, without
35   *    prior written permission of the Apache Software Foundation.
36   *
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   *
51   * This software consists of voluntary contributions made by many
52   * individuals on behalf of the Apache Software Foundation.  For more
53   * information on the Apache Software Foundation, please see
54   * <http://www.apache.org/>.
55   */
56  
57  import java.io.Writer  ;
58  
59  import org.apache.fulcrum.ServiceException;
60  import org.apache.fulcrum.TurbineServices;
61  import org.apache.fulcrum.template.TemplateService;
62  import org.apache.turbine.RunData;
63  import org.apache.turbine.TemplateContext;
64  import org.apache.turbine.Turbine;
65  import org.apache.turbine.services.pull.ApplicationTool;
66  import org.apache.turbine.services.pull.PullService;
67  
68  /**
69   * <p>Responsible for populating contexts (can be thought of as "context
70   * builders").  Modules can be aggregated in an arbitrary fashion to
71   * render content.</p>
72   *
73   * <p>Though there is no longer an explict definition of the
74   * screen/navigation/layout system used in Turbine 2, this classic
75   * model is still a valid usage pattern.  See <a
76   * HREF="http://scarab.tigris.org/">Scarab</a> for an example of an
77   * application built using the <code>Module</code> class which follows
78   * the classic pattern.</p>
79   *
80   * @author <a HREF="mailto:jvanzyl@apache.org">Jason van Zyl</a>
81   * @version $Id: Module.java,v 1.9 2004/11/12 10:26:31 epugh Exp $
82   */
83  public class Module
84  {
85      /**
86       * A subclass must override this method to build itself.
87       * Subclasses override this method to store the layout in RunData
88       * or to write the layout to the output stream referenced in
89       * RunData.
90       *
91       * @param data Turbine information.
92       * @exception Exception a generic exception.
93       */
94      protected String   doBuild( RunData data )
95          throws Exception  
96      {
97          doBuildTemplate(data);
98          return "";
99      }
100 
101     /**
102      * Subclasses can override this method to add additional
103      * functionality.  This method is protected to force clients to
104      * use LayoutLoader to build a Layout.
105      *
106      * @param data Turbine information.
107      * @exception Exception a generic exception.
108      */
109     protected String   build( RunData data )
110         throws Exception  
111     {
112         return doBuild( data );
113     }
114 
115     public String   evaluate(RunData data)
116         throws Exception  
117     {
118         return doBuild(data);
119     }
120 
121     public void execute(RunData data)
122         throws Exception  
123     {
124         doBuild(data);
125     }
126 
127     /**
128      * This method should be overidden by subclasses that wish to add
129      * specific business logic.
130      *
131      * @param data Turbine information.
132      * @exception Exception a generic exception.
133      */
134     protected void doBuildTemplate( RunData data, TemplateContext context)
135         throws Exception  
136     {
137     }
138 
139     protected void doBuildTemplate( RunData data )
140         throws Exception  
141     {
142         doBuildTemplate(data, getTemplateContext(data));
143     }
144 
145     /**
146      * Populates the TemplateContext with Pull Tools and the
147      * RunData object.
148      *
149      * @param data Turbine information.
150      */
151     public static TemplateContext getTemplateContext(RunData data)
152     {
153         // Attempt to get it from the data first.  If it doesn't
154         // exist, create it and then stuff it into the data.
155         TemplateContext context =
156             (TemplateContext) data.getTemp(Turbine.CONTEXT);
157 
158         if (context == null)
159         {
160             context = getPullService().getRuntimeContext(data);
161             context.put ( "data", data );
162             data.setTemp(Turbine.CONTEXT, context);
163         }
164         return context;
165     }
166 
167     public static String   handleRequest(TemplateContext context, String   template)
168         throws ServiceException
169     {
170         return getTemplateService().handleRequest(new ContextAdapter(context), template);
171     }
172 
173     public static void handleRequest(TemplateContext context, 
174                                        String   template, Writer   writer)
175         throws ServiceException
176     {
177         getTemplateService().handleRequest(new ContextAdapter(context), 
178                                       template, writer);
179     }
180 
181     public static boolean templateExists(String   template)
182     {
183         return getTemplateService().templateExists(template);
184     }
185 
186     /**
187      * Performs post-request actions (releases context
188      * tools back to the object pool).
189      *
190      * @param context a Velocity Context
191      */
192     public static void requestFinished(TemplateContext context)
193     {
194         getPullService().releaseTools(context);
195     }
196 
197     /**
198      * Helper method that allows you to easily get a tool
199      * from a Context. Essentially, it just does the cast
200      * to an Application tool for you.
201      *
202      * @param context a Velocity Context to get tools from
203      * @param name the name of the tool to get
204      * @return ApplicationTool null if no tool could be found
205      */
206     public static ApplicationTool getTool(TemplateContext context,
207                                           String   name)
208     {
209         try
210         {
211             return (ApplicationTool) context.get(name);
212         }
213         catch (Exception   e)
214         {
215             return null;
216         }
217     }
218 
219     /**
220      * This method is used when you want to short circuit a Screen and
221      * change the template that will be executed next. <b>Note that the current
222      * context will be applied to the next template that is executed.
223      * If you want to have the context executed for the next screen,
224      * to be the same one as the next screen, then you should use the
225      * TemplateScreen.doRedirect() method.</b>
226      *
227      * @param data Turbine information.
228      * @param template The name of the next template.
229      * @deprecated use setTarget(data,template)
230      */
231     public static void setTemplate(RunData data, String   template)
232     {
233         setTarget(data,template);
234     }
235 
236     public static void setTarget(RunData data, String   template)
237     {
238         data.setTarget(template);
239     }
240     
241     /**
242      * Utility method for accessing the service
243      * implementation
244      *
245      * @return a PullService implementation instance
246      */
247     protected static PullService getPullService()
248     {
249         return (PullService)TurbineServices
250             .getInstance().getService(PullService.SERVICE_NAME);
251     }        
252 
253     /**
254      * Utility method for accessing the service
255      * implementation
256      *
257      * @return a TemplateService implementation instance
258      */
259     protected static TemplateService getTemplateService()
260     {
261         return (TemplateService)TurbineServices
262             .getInstance().getService(TemplateService.SERVICE_NAME);
263     }  
264 }
265
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags