View Javadoc

1   package org.apache.turbine.util;
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 java.io.BufferedInputStream;
20  import java.io.File;
21  import java.io.FileInputStream;
22  import java.io.FileNotFoundException;
23  import java.io.InputStream;
24  import java.net.MalformedURLException;
25  import java.net.URL;
26  import java.util.Enumeration;
27  import java.util.HashMap;
28  import java.util.Map;
29  import java.util.Set;
30  import java.util.Vector;
31  import javax.servlet.RequestDispatcher;
32  import javax.servlet.Servlet;
33  import javax.servlet.ServletConfig;
34  import javax.servlet.ServletContext;
35  
36  import org.apache.commons.logging.Log;
37  import org.apache.commons.logging.LogFactory;
38  import org.apache.avalon.framework.activity.Disposable;
39  import org.apache.avalon.framework.activity.Initializable;
40  import org.apache.turbine.Turbine;
41  
42  /***
43   * A class used for initialization of Turbine without a servlet container.
44   * <p>
45   * If you need to use Turbine outside of a servlet container, you can
46   * use this class for initialization of the Turbine servlet.
47   * <p>
48   * <blockquote><code><pre>
49   * TurbineConfig config = new TurbineConfig(".", "conf/TurbineResources.properties");
50   * </pre></code></blockquote>
51   * <p>
52   * All paths referenced in TurbineResources.properties and the path to
53   * the properties file itself (the second argument) will be resolved
54   * relative to the directory given as the first argument of the constructor,
55   * here - the directory where application was started. Don't worry about
56   * discarding the references to objects created above. They are not needed,
57   * once everything is initialized.
58   * <p>
59   * In order to initialize the Services Framework outside of the Turbine Servlet,
60   * you need to call the <code>init()</code> method. By default, this will
61   * initialize the Resource and Logging Services and any other services you
62   * have defined in your TurbineResources.properties file.
63   *
64   * @todo Make this class enforce the lifecycle contracts
65   *
66   * @author <a href="mailto:quintonm@bellsouth.net">Quinton McCombs</a>
67   * @author <a href="mailto:krzewski@e-point.pl">Rafal Krzewski</a>
68   * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
69   * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
70   * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
71   * @author <a href="mailto:epugh@upstate.com">Eric Pugh</a>
72   * @version $Id: TurbineConfig.java 264148 2005-08-29 14:21:04Z henning $
73   */
74  public class TurbineConfig
75          implements ServletConfig, ServletContext, Initializable, Disposable
76  {
77      /***
78       * Servlet initialization parameter name for the path to
79       * TurbineConfiguration.xml file used by Turbine
80       */
81      public static final String CONFIGURATION_PATH_KEY = "configuration";
82  
83      /***
84       * Servlet initialization parameter name for the path to
85       * Turbine.properties file used by Turbine
86       */
87      public static final String PROPERTIES_PATH_KEY = "properties";
88  
89      /***
90       * Default value of TurbineResources.properties file path
91       * (<code>/WEB-INF/conf/TurbineResources.properties</code>).
92       */
93      public static final String PROPERTIES_PATH_DEFAULT =
94              "/WEB-INF/conf/TurbineResources.properties";
95  
96      /*** Filenames are looked up in this directory. */
97      protected File root;
98  
99      /*** Servlet container (or emulator) attributes. */
100     protected Map attributes;
101 
102     /*** Turbine servlet initialization parameters. */
103     protected Map initParams;
104 
105     /*** The Turbine servlet instance used for initialization. */
106     private Turbine turbine;
107 
108     /*** Logging */
109     private Log log = LogFactory.getLog(this.getClass());
110 
111     /***
112      * Constructs a new TurbineConfig.
113      *
114      * This is the general form of the constructor. You can provide
115      * a path to search for files, and a name-value map of init
116      * parameters.
117      *
118      * <p> For the list of recognized init parameters, see
119      * {@link org.apache.turbine.Turbine} class.
120      *
121      * @param path The web application root (i.e. the path for file lookup).
122      * @param attributes Servlet container (or emulator) attributes.
123      * @param initParams initialization parameters.
124      */
125     public TurbineConfig(String path, Map attributes, Map initParams)
126     {
127         root = new File(path);
128         this.attributes = attributes;
129         this.initParams = initParams;
130     }
131 
132     /***
133      * @see #TurbineConfig(String path, Map attributes, Map initParams)
134      */
135     public TurbineConfig(String path, Map initParams)
136     {
137         this(path, new HashMap(0), initParams);
138     }
139 
140     /***
141      * Constructs a TurbineConfig.
142      *
143      * This is a specialized constructor that allows to configure
144      * Turbine easiliy in the common setups.
145      *
146      * @param path The web application root (i.e. the path for file lookup).
147      * @param properties the relative path to TurbineResources.properties file
148      */
149     public TurbineConfig(String path, String properties)
150     {
151         this(path, new HashMap(1));
152         initParams.put(PROPERTIES_PATH_KEY, properties);
153     }
154 
155     /***
156      * Causes this class to initialize itself which in turn initializes
157      * all of the Turbine Services that need to be initialized.
158      *
159      * @see org.apache.stratum.lifecycle.Initializable
160      */
161     public void initialize()
162     {
163         try
164         {
165             turbine = new Turbine();
166             turbine.init(this);
167         }
168         catch (Exception e)
169         {
170             log.error("TurbineConfig: Initialization failed", e);
171         }
172     }
173 
174     /***
175      * Initialization requiring a HTTP <code>GET</code> request.
176      */
177     public void init(RunData data)
178     {
179         if (turbine != null)
180         {
181             turbine.init(data);
182         }
183     }
184 
185     /***
186      * Shutdown the Turbine System, lifecycle style
187      *
188      */
189     public void dispose()
190     {
191         if (turbine != null)
192         {
193             turbine.destroy();
194         }
195     }
196 
197     /***
198      * Returns a reference to the object cast onto ServletContext type.
199      *
200      * @return a ServletContext reference
201      */
202     public ServletContext getServletContext()
203     {
204         return this;
205     }
206 
207     /***
208      * Translates a path relative to the web application root into an
209      * absolute path.
210      *
211      * @param path A path relative to the web application root.
212      * @return An absolute version of the supplied path, or <code>null</code>
213      * if the translated path doesn't map to a file or directory.
214      */
215     public String getRealPath(String path)
216     {
217         String result = null;
218         File f = new File(root, path);
219 
220         if (log.isDebugEnabled())
221         {
222             StringBuffer sb = new StringBuffer();
223 
224             sb.append("TurbineConfig.getRealPath: path '");
225             sb.append(path);
226             sb.append("' translated to '");
227             sb.append(f.getPath());
228             sb.append("' ");
229             sb.append(f.exists() ? "" : "not ");
230             sb.append("found");
231             log.debug(sb.toString());
232         }
233 
234         if (f.exists())
235         {
236           result = f.getPath();
237         }
238         else
239         {
240             log.error("getRealPath(\"" + path + "\") is undefined, returning null");
241         }
242 
243         return result;
244     }
245 
246     /***
247      * Retrieves an initialization parameter.
248      *
249      * @param name the name of the parameter.
250      * @return the value of the parameter.
251      */
252     public String getInitParameter(String name)
253     {
254         return (String) initParams.get(name);
255     }
256 
257     /***
258      * Retrieves an Enumeration of initialization parameter names.
259      *
260      * @return an Enumeration of initialization parameter names.
261      */
262     public Enumeration getInitParameterNames()
263     {
264         return new Vector(initParams.keySet()).elements();
265     }
266 
267     /***
268      * Returns the servlet name.
269      *
270      * Fixed value "Turbine" is returned.
271      *
272      * @return the servlet name.
273      */
274     public String getServletName()
275     {
276         return "Turbine";
277     }
278 
279     /***
280      * Returns the context name.
281      *
282      * Fixed value "Turbine" is returned
283      *
284      * @return the context name
285      */
286     public String getServletContextName()
287     {
288         return "Turbine";
289     }
290 
291     /***
292      * Returns a URL to the resource that is mapped to a specified
293      * path. The path must begin with a "/" and is interpreted
294      * as relative to the current context root.
295      *
296      * @param s the path to the resource
297      * @return a URL pointing to the resource
298      * @exception MalformedURLException
299      */
300     public URL getResource(String s)
301             throws MalformedURLException
302     {
303         return new URL("file://" + getRealPath(s));
304     }
305 
306     /***
307      * Returns the resource located at the named path as
308      * an <code>InputStream</code> object.
309      *
310      * @param s the path to the resource
311      * @return an InputStream object from which the resource can be read
312      */
313     public InputStream getResourceAsStream(String s)
314     {
315         try
316         {
317             FileInputStream fis = new FileInputStream(getRealPath(s));
318             return new BufferedInputStream(fis);
319         }
320         catch (FileNotFoundException e)
321         {
322             return null;
323         }
324     }
325 
326     /***
327      * Logs an error message.
328      *
329      * @param e an Exception.
330      * @param m a message.
331      * @deprecated use log(String,Throwable) instead
332      */
333     public void log(Exception e, String m)
334     {
335         log.info(m, e);
336     }
337 
338     /***
339      * Logs a message.
340      *
341      * @param m a message.
342      */
343     public void log(String m)
344     {
345         log.info(m);
346     }
347 
348     /***
349      * Logs an error message.
350      *
351      * @param t a Throwable object.
352      * @param m a message.
353      */
354     public void log(String m, Throwable t)
355     {
356         log.info(m, t);
357     }
358 
359     /***
360      * Returns the servlet container attribute with the given name, or
361      * null if there is no attribute by that name.
362      */
363     public Object getAttribute(String s)
364     {
365         return attributes.get(s);
366     }
367 
368     /***
369      * Returns an Enumeration containing the attribute names available
370      * within this servlet context.
371      */
372     public Enumeration getAttributeNames()
373     {
374         return new Vector(attributes.keySet()).elements();
375     }
376 
377     // Unimplemented methods follow
378 
379     /***
380      * Not implemented.
381      *
382      * A method in ServletConfig or ServletContext interface that is not
383      * implemented and will throw <code>UnsuportedOperationException</code>
384      * upon invocation
385      */
386     public ServletContext getContext(String s)
387     {
388         throw new UnsupportedOperationException();
389     }
390 
391     /***
392      * Not implemented.
393      *
394      * A method in ServletConfig or ServletContext interface that is not
395      * implemented and will throw <code>UnsuportedOperationException</code>
396      * upon invocation
397      */
398     public int getMajorVersion()
399     {
400         throw new UnsupportedOperationException();
401     }
402 
403     /***
404      * Not implemented.
405      *
406      * A method in ServletConfig or ServletContext interface that is not
407      * implemented and will throw <code>UnsuportedOperationException</code>
408      * upon invocation
409      */
410     public String getMimeType(String s)
411     {
412         throw new UnsupportedOperationException();
413     }
414 
415     /***
416      * Not implemented.
417      *
418      * A method in ServletConfig or ServletContext interface that is not
419      * implemented and will throw <code>UnsuportedOperationException</code>
420      * upon invocation
421      */
422     public int getMinorVersion()
423     {
424         throw new UnsupportedOperationException();
425     }
426 
427     /***
428      * Not implemented.
429      *
430      * A method in ServletConfig or ServletContext interface that is not
431      * implemented and will throw <code>UnsuportedOperationException</code>
432      * upon invocation
433      */
434     public RequestDispatcher getNamedDispatcher(String s)
435     {
436         throw new UnsupportedOperationException();
437     }
438 
439     /***
440      * Not implemented.
441      *
442      * A method in ServletConfig or ServletContext interface that is not
443      * implemented and will throw <code>UnsuportedOperationException</code>
444      * upon invocation
445      */
446     public RequestDispatcher getRequestDispatcher(String s)
447     {
448         throw new UnsupportedOperationException();
449     }
450 
451     /***
452      * Not implemented.
453      *
454      * A method in ServletContext (2.3) interface that is not implemented and
455      * will throw <code>UnsuportedOperationException</code> upon invocation
456      */
457     public Set getResourcePaths(String s)
458     {
459         throw new UnsupportedOperationException();
460     }
461 
462     /***
463      * Not implemented.
464      *
465      * A method in ServletContext (2.3) interface that is not implemented and
466      * will throw <code>UnsuportedOperationException</code> upon invocation
467      */
468     public String getServerInfo()
469     {
470         throw new UnsupportedOperationException();
471     }
472 
473     /***
474      * Not implemented.
475      *
476      * A method in ServletContext interface that is not implemented and will
477      * throw <code>UnsuportedOperationException</code> upon invocation
478      * @deprecated As of Java Servlet API 2.1, with no direct replacement.
479      */
480     public Servlet getServlet(String s)
481     {
482         throw new UnsupportedOperationException();
483     }
484 
485     /***
486      * Not implemented.
487      *
488      * A method in ServletContext interface that is not implemented and will
489      * throw <code>UnsuportedOperationException</code> upon invocation
490      * @deprecated As of Java Servlet API 2.1, with no replacement.
491      */
492     public Enumeration getServletNames()
493     {
494         throw new UnsupportedOperationException();
495     }
496 
497     /***
498      * Not implemented.
499      *
500      * A method in ServletContext interface that is not implemented and will
501      * throw <code>UnsuportedOperationException</code> upon invocation
502      * @deprecated As of Java Servlet API 2.0, with no replacement.
503      */
504     public Enumeration getServlets()
505     {
506         throw new UnsupportedOperationException();
507     }
508 
509     /***
510      * Not implemented.
511      *
512      * A method in ServletContext interface that is not implemented and will
513      * throw <code>UnsuportedOperationException</code> upon invocation
514      */
515     public void removeAttribute(String s)
516     {
517         throw new UnsupportedOperationException();
518     }
519 
520     /***
521      * Not implemented.
522      *
523      * A method in ServletContext interface that is not implemented and will
524      * throw <code>UnsuportedOperationException</code> upon invocation
525      */
526     public void setAttribute(String s, Object o)
527     {
528         throw new UnsupportedOperationException();
529     }
530 }