DigestingPlugIn xref

View Javadoc

    1   /*
    2    * $Id: DigestingPlugIn.java 471754 2006-11-06 14:55:09Z husted $
    3    *
    4    * Licensed to the Apache Software Foundation (ASF) under one
    5    * or more contributor license agreements.  See the NOTICE file
    6    * distributed with this work for additional information
    7    * regarding copyright ownership.  The ASF licenses this file
    8    * to you under the Apache License, Version 2.0 (the
    9    * "License"); you may not use this file except in compliance
    10   * with the License.  You may obtain a copy of the License at
    11   *
    12   *  http://www.apache.org/licenses/LICENSE-2.0
    13   *
    14   * Unless required by applicable law or agreed to in writing,
    15   * software distributed under the License is distributed on an
    16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    17   * KIND, either express or implied.  See the License for the
    18   * specific language governing permissions and limitations
    19   * under the License.
    20   */
    21  package org.apache.struts.plugins;
    22
    23  import org.apache.commons.digester.Digester;
    24  import org.apache.commons.digester.RuleSet;
    25  import org.apache.commons.digester.xmlrules.DigesterLoader;
    26  import org.apache.commons.logging.Log;
    27  import org.apache.commons.logging.LogFactory;
    28  import org.apache.struts.action.ActionServlet;
    29  import org.apache.struts.action.PlugIn;
    30  import org.apache.struts.config.ModuleConfig;
    31  import org.apache.struts.util.RequestUtils;
    32  import org.xml.sax.SAXException;
    33
    34  import javax.servlet.ServletException;
    35
    36  import java.io.File;
    37  import java.io.IOException;
    38
    39  import java.net.URL;
    40  import java.net.URLConnection;
    41
    42  /**
    43   * <p>An implementation of <code>PlugIn</code> which can be configured to
    44   * instantiate a graph of objects using the Commons Digester and place the
    45   * root object of that graph into the Application context.</p>
    46   *
    47   * @version $Rev: 471754 $
    48   * @see org.apache.struts.action.PlugIn
    49   * @since Struts 1.2
    50   */
    51  public class DigestingPlugIn implements PlugIn {
    52      /**
    53       * Commons Logging instance.
    54       */
    55      private static Log log = LogFactory.getLog(DigestingPlugIn.class);
    56      protected static final String SOURCE_CLASSPATH = "classpath";
    57      protected static final String SOURCE_FILE = "file";
    58      protected static final String SOURCE_SERVLET = "servlet";
    59      protected String configPath = null;
    60      protected String configSource = SOURCE_SERVLET;
    61      protected String digesterPath = null;
    62      protected String digesterSource = SOURCE_SERVLET;
    63      protected String key = null;
    64      protected ModuleConfig moduleConfig = null;
    65      protected String rulesets = null;
    66      protected ActionServlet servlet = null;
    67      protected boolean push = false;
    68
    69      /**
    70       * Constructor for DigestingPlugIn.
    71       */
    72      public DigestingPlugIn() {
    73          super();
    74      }
    75
    76      /**
    77       * Receive notification that our owning module is being shut down.
    78       */
    79      public void destroy() {
    80          this.servlet = null;
    81          this.moduleConfig = null;
    82      }
    83
    84      /**
    85       * <p>Initialize a <code>Digester</code> and use it to parse a
    86       * configuration file, resulting in a root object which will be placed
    87       * into the ServletContext.</p>
    88       *
    89       * @param servlet ActionServlet that is managing all the modules in this
    90       *                web application
    91       * @param config  ModuleConfig for the module with which this plug-in is
    92       *                associated
    93       * @throws ServletException if this <code>PlugIn</code> cannot be
    94       *                          successfully initialized
    95       */
    96      public void init(ActionServlet servlet, ModuleConfig config)
    97          throws ServletException {
    98          this.servlet = servlet;
    99          this.moduleConfig = config;
    100
    101         Object obj = null;
    102
    103         Digester digester = this.initializeDigester();
    104
    105         if (this.push) {
    106             log.debug("push == true; pushing plugin onto digester stack");
    107             digester.push(this);
    108         }
    109
    110         try {
    111             log.debug("XML data file: [path: " + this.configPath + ", source: "
    112                 + this.configSource + "]");
    113
    114             URL configURL =
    115                 this.getConfigURL(this.configPath, this.configSource);
    116
    117             if (configURL == null) {
    118                 throw new ServletException(
    119                     "Unable to locate XML data file at [path: "
    120                     + this.configPath + ", source: " + this.configSource + "]");
    121             }
    122
    123             URLConnection conn = configURL.openConnection();
    124
    125             conn.setUseCaches(false);
    126             conn.connect();
    127             obj = digester.parse(conn.getInputStream());
    128         } catch (IOException e) {
    129             // TODO Internationalize msg
    130             log.error("Exception processing config", e);
    131             throw new ServletException(e);
    132         } catch (SAXException e) {
    133             // TODO Internationalize msg
    134             log.error("Exception processing config", e);
    135             throw new ServletException(e);
    136         }
    137
    138         this.storeGeneratedObject(obj);
    139     }
    140
    141     /**
    142      * Initialize the <code>Digester</code> which will be used to process the
    143      * main configuration.
    144      *
    145      * @return a Digester, ready to use.
    146      * @throws ServletException
    147      */
    148     protected Digester initializeDigester()
    149         throws ServletException {
    150         Digester digester = null;
    151
    152         if ((this.digesterPath != null) && (this.digesterSource != null)) {
    153             try {
    154                 log.debug("Initialize digester from XML [path: "
    155                     + this.digesterPath + "; source: " + this.digesterSource
    156                     + "]");
    157                 digester =
    158                     this.digesterFromXml(this.digesterPath, this.digesterSource);
    159             } catch (IOException e) {
    160                 // TODO Internationalize msg
    161                 log.error("Exception instantiating digester from XML ", e);
    162                 throw new ServletException(e);
    163             }
    164         } else {
    165             log.debug("No XML rules for digester; call newDigesterInstance()");
    166             digester = this.newDigesterInstance();
    167         }
    168
    169         this.applyRuleSets(digester);
    170
    171         return digester;
    172     }
    173
    174     /**
    175      * <p>Instantiate a <code>Digester</code>.</p> <p>Subclasses may wish to
    176      * override this to provide a subclass of Digester, or to configure the
    177      * Digester using object methods.</p>
    178      *
    179      * @return a basic instance of <code>org.apache.commons.digester.Digester</code>
    180      */
    181     protected Digester newDigesterInstance() {
    182         return new Digester();
    183     }
    184
    185     /**
    186      * <p>Instantiate a Digester from an XML input stream using the Commons
    187      * <code>DigesterLoader</code>.</p>
    188      *
    189      * @param path   the path to the digester rules XML to be found using
    190      *               <code>source</code>
    191      * @param source a string indicating the lookup method to be used with
    192      *               <code>path</code>
    193      * @return a configured Digester
    194      * @throws FileNotFoundException
    195      * @throws MalformedURLException
    196      * @see #getConfigURL(String, String)
    197      */
    198     protected Digester digesterFromXml(String path, String source)
    199         throws IOException {
    200         URL configURL = this.getConfigURL(path, source);
    201
    202         if (configURL == null) {
    203             throw new NullPointerException("No resource '" + path
    204                 + "' found in '" + source + "'");
    205         }
    206
    207         return DigesterLoader.createDigester(configURL);
    208     }
    209
    210     /**
    211      * Instantiate any <code>RuleSet</code> classes defined in the
    212      * <code>rulesets</code> property and use them to add rules to our
    213      * <code>Digester</code>.
    214      *
    215      * @param digester the Digester instance to add RuleSet objects to.
    216      * @throws ServletException
    217      */
    218     protected void applyRuleSets(Digester digester)
    219         throws ServletException {
    220         if ((this.rulesets == null) || (this.rulesets.trim().length() == 0)) {
    221             return;
    222         }
    223
    224         rulesets = rulesets.trim();
    225
    226         String ruleSet = null;
    227
    228         while (rulesets.length() > 0) {
    229             int comma = rulesets.indexOf(",");
    230
    231             if (comma < 0) {
    232                 ruleSet = rulesets.trim();
    233                 rulesets = "";
    234             } else {
    235                 ruleSet = rulesets.substring(0, comma).trim();
    236                 rulesets = rulesets.substring(comma + 1).trim();
    237             }
    238
    239             if (log.isDebugEnabled()) {
    240                 // TODO Internationalize msg
    241                 log.debug("Configuring custom Digester Ruleset of type "
    242                     + ruleSet);
    243             }
    244
    245             try {
    246                 RuleSet instance =
    247                     (RuleSet) RequestUtils.applicationInstance(ruleSet);
    248
    249                 digester.addRuleSet(instance);
    250             } catch (Exception e) {
    251                 // TODO Internationalize msg
    252                 log.error("Exception configuring custom Digester RuleSet", e);
    253                 throw new ServletException(e);
    254             }
    255         }
    256     }
    257
    258     /**
    259      * <p>Look up a resource path using one of a set of known path resolution
    260      * mechanisms and return a URL to the resource.</p>
    261      *
    262      * @param path   a String which is meaningful to one of the known
    263      *               resolution mechanisms.
    264      * @param source one of the known path resolution mechanisms:
    265      *
    266      *               <ul>
    267      *
    268      *               <li>file - the path is a fully-qualified filesystem
    269      *               path.</li>
    270      *
    271      *               <li>servlet - the path is a servlet-context relative
    272      *               path.</li>
    273      *
    274      *               <li>classpath - the path is a classpath-relative
    275      *               path.</li>
    276      *
    277      *               </ul>
    278      * @return a URL pointing to the given path in the given mechanism.
    279      * @throws java.io.FileNotFoundException
    280      * @throws java.net.MalformedURLException
    281      */
    282     protected URL getConfigURL(String path, String source)
    283         throws IOException {
    284         if (SOURCE_CLASSPATH.equals(source)) {
    285             return this.getClassPathURL(path);
    286         }
    287
    288         if (SOURCE_FILE.equals(source)) {
    289             return this.getFileURL(path);
    290         }
    291
    292         if (SOURCE_SERVLET.equals(source)) {
    293             return this.getServletContextURL(path);
    294         }
    295
    296         // TODO Internationalize msg
    297         throw new IllegalArgumentException("ConfigSource " + source
    298             + " is not recognized");
    299     }
    300
    301     /**
    302      * Given a string, return a URL to a classpath resource of that name.
    303      *
    304      * @param path a Classpath-relative string identifying a resource.
    305      * @return a URL identifying the resource on the classpath. TODO Do we
    306      *         need to be smarter about ClassLoaders?
    307      */
    308     protected URL getClassPathURL(String path) {
    309         return getClass().getClassLoader().getResource(path);
    310     }
    311
    312     /**
    313      * Given a string, return a URL to a Servlet Context resource of that
    314      * name.
    315      *
    316      * @param path a Classpath-relative string identifying a resource.
    317      * @return a URL identifying the resource in the Servlet Context
    318      * @throws MalformedURLException
    319      */
    320     protected URL getServletContextURL(String path)
    321         throws IOException {
    322         return this.servlet.getServletContext().getResource(path);
    323     }
    324
    325     /**
    326      * Given a string, return a URL to a Filesystem resource of that name.
    327      *
    328      * @param path a path to a file.
    329      * @return a URL identifying the resource in the in the file system.
    330      * @throws MalformedURLException
    331      * @throws FileNotFoundException
    332      */
    333     protected URL getFileURL(String path)
    334         throws IOException {
    335         File file = new File(path);
    336
    337         return file.toURL();
    338     }
    339
    340     /**
    341      * @param configPath the path to configuration information for this
    342      *                   PlugIn.
    343      * @see #configSource
    344      */
    345     public void setConfigPath(String configPath) {
    346         this.configPath = configPath;
    347     }
    348
    349     /**
    350      * @return the configPath property
    351      * @see #configSource
    352      */
    353     public String getConfigPath() {
    354         return configPath;
    355     }
    356
    357     /**
    358      * Set the source of the config file.  Should be one of the following:
    359      * <ul> <li> "classpath" - indicates that the configPath will be resolved
    360      * by the ClassLoader. </li> <li> "file" - indicates that the configPath
    361      * is a fully-qualified filesystem path. </li> <li> "servlet" - indicates
    362      * that the configPath will be found by the ServletContext. </li> </ul>
    363      *
    364      * @param configSource the source (lookup method) for the config file.
    365      * @see #configPath
    366      */
    367     public void setConfigSource(String configSource) {
    368         this.configSource = configSource;
    369     }
    370
    371     /**
    372      * @return the string describing which access method should be used to
    373      *         resolve configPath.
    374      * @see #configPath
    375      */
    376     public String getConfigSource() {
    377         return configSource;
    378     }
    379
    380     /**
    381      * This method is called after the Digester runs to store the generated
    382      * object somewhere.  This implementation places the given object into the
    383      * ServletContext under the attribute name as defined in
    384      * <code>key</code>.
    385      *
    386      * @param obj The object to save.
    387      */
    388     protected void storeGeneratedObject(Object obj) {
    389         log.debug("Put [" + obj + "] into application context [key:" + this.key
    390             + "]");
    391         this.servlet.getServletContext().setAttribute(this.getKey(), obj);
    392     }
    393
    394     /**
    395      * @param key The ServletContext attribute name to store the generated
    396      *            object under.
    397      */
    398     public void setKey(String key) {
    399         this.key = key;
    400     }
    401
    402     /**
    403      * @return The ServletContext attribute name the generated object is
    404      *         stored under.
    405      */
    406     public String getKey() {
    407         return key;
    408     }
    409
    410     /**
    411      * <p>A comma-delimited list of one or more classes which implement
    412      * <code>org.apache.commons.digester.RuleSet</code>. (Optional)</p>
    413      */
    414     public void setRulesets(String ruleSets) {
    415         this.rulesets = ruleSets;
    416     }
    417
    418     /**
    419      * @return The configured list of <code>RuleSet</code> classes.
    420      */
    421     public String getRulesets() {
    422         return this.rulesets;
    423     }
    424
    425     /**
    426      * <p>The path to a Digester XML configuration file, relative to the
    427      * <code>digesterSource</code> property. (Optional)</p>
    428      *
    429      * @see #digesterSource
    430      * @see #getConfigURL(String, String)
    431      */
    432     public void setDigesterPath(String digesterPath) {
    433         this.digesterPath = digesterPath;
    434     }
    435
    436     /**
    437      * @return the configured path to a Digester XML config file, or null.
    438      * @see #digesterSource
    439      * @see #getConfigURL(String, String)
    440      */
    441     public String getDigesterPath() {
    442         return digesterPath;
    443     }
    444
    445     /**
    446      * <p>The lookup mechanism to be used to resolve <code>digesterPath</code>
    447      * (optional). </p>
    448      *
    449      * @param digesterSource
    450      * @see #getConfigURL(String, String)
    451      */
    452     public void setDigesterSource(String digesterSource) {
    453         this.digesterSource = digesterSource;
    454     }
    455
    456     /**
    457      * @return the configured lookup mechanism for resolving
    458      *         <code>digesterPath</code>.
    459      * @see #getConfigURL(String, String)
    460      */
    461     public String getDigesterSource() {
    462         return this.digesterSource;
    463     }
    464
    465     /**
    466      * <p>If set to <code>true</code>, this PlugIn will be pushed onto the
    467      * Digester stack before the digester <code>parse</code> method is
    468      * called.</p> <p>Defaults to <code>false</code></p>
    469      *
    470      * @param push
    471      */
    472     public void setPush(boolean push) {
    473         this.push = push;
    474     }
    475
    476     /**
    477      * @return Whether or not this <code>PlugIn</code> instance will be pushed
    478      *         onto the <code>Digester</code> stack before
    479      *         <code>digester.parse()</code> is called.
    480      */
    481     public boolean getPush() {
    482         return this.push;
    483     }
    484 }