KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > commons > digester > plugins > Declaration


1 /* $Id: Declaration.java 179714 2005-06-03 03:53:39Z skitching $
2  *
3  * Copyright 2003-2004 The Apache Software Foundation.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 package org.apache.commons.digester.plugins;
18
19 import java.util.Properties JavaDoc;
20
21 import org.apache.commons.logging.Log;
22 import org.apache.commons.digester.Digester;
23
24 /**
25  * Represents a Class that can be instantiated by a PluginCreateRule, plus
26  * info on how to load custom digester rules for mapping xml into that
27  * plugged-in class.
28  *
29  * @since 1.6
30  */
31 public class Declaration {
32    
33     /** The class of the object to be instantiated. */
34     private Class JavaDoc pluginClass;
35
36     /** The name of the class of the object to be instantiated. */
37     private String JavaDoc pluginClassName;
38     
39     /** See {@link #setId}. */
40     private String JavaDoc id;
41     
42     /** See {@link #setProperties}. */
43     private Properties JavaDoc properties = new Properties JavaDoc();
44     
45     /** See {@link #init}. */
46     private boolean initialized = false;
47
48     /**
49      * Class which is responsible for dynamically loading this
50      * plugin's rules on demand.
51      */
52     private RuleLoader ruleLoader = null;
53     
54     //---------------------- constructors ----------------------------------
55
56     /**
57      * Constructor.
58      */
59     public Declaration(String JavaDoc pluginClassName) {
60         // We can't load the pluginClass at this time, because we don't
61 // have a digester instance yet to load it through. So just
62 // save the name away, and we'll load the Class object in the
63 // init method.
64 this.pluginClassName = pluginClassName;
65     }
66     
67     /**
68      * Constructor.
69      */
70     public Declaration(Class JavaDoc pluginClass) {
71         this.pluginClass = pluginClass;
72         this.pluginClassName = pluginClass.getName();
73     }
74     
75     /**
76      * Create an instance where a fully-initialised ruleLoader instance
77      * is provided by the caller instead of having the PluginManager
78      * "discover" an appropriate one.
79      */
80     public Declaration(Class JavaDoc pluginClass, RuleLoader ruleLoader) {
81         this.pluginClass = pluginClass;
82         this.pluginClassName = pluginClass.getName();
83         this.ruleLoader = ruleLoader;
84     }
85     
86     //---------------------- properties -----------------------------------
87
88     /**
89      * The id that the user associated with a particular plugin declaration
90      * in the input xml. This id is later used in the input xml to refer
91      * back to the original declaration.
92      * <p>
93      * For plugins declared "in-line", the id is null.
94      */
95     public void setId(String JavaDoc id) {
96         this.id = id;
97     }
98     
99     /**
100      * Return the id associated with this declaration. For plugins
101      * declared "inline", null will be returned.
102      *
103      * @return The id value. May be null.
104      */
105     public String JavaDoc getId() {
106         return id;
107     }
108
109     /**
110      * Copy all (key,value) pairs in the param into the properties member of
111      * this object.
112      * <p>
113      * The declaration properties cannot be explicit member variables,
114      * because the set of useful properties a user can provide on a declaration
115      * depends on what RuleFinder classes are available - and extra RuleFinders
116      * can be added by the user. So here we keep a map of the settings, and
117      * let the RuleFinder objects look for whatever properties they consider
118      * significant.
119      * <p>
120      * The "id" and "class" properties are treated differently.
121      */
122     public void setProperties(Properties JavaDoc p) {
123         properties.putAll(p);
124     }
125     
126     /**
127      * Return plugin class associated with this declaration.
128      *
129      * @return The pluginClass.
130      */
131     public Class JavaDoc getPluginClass() {
132         return pluginClass;
133     }
134
135     //---------------------- methods -----------------------------------
136
137     /**
138      * Must be called exactly once, and must be called before any call
139      * to the configure method.
140      */
141     public void init(Digester digester, PluginManager pm) throws PluginException {
142         Log log = digester.getLogger();
143         boolean debug = log.isDebugEnabled();
144         if (debug) {
145             log.debug("init being called!");
146         }
147         
148         if (initialized) {
149             throw new PluginAssertionFailure("Init called multiple times.");
150         }
151
152         if ((pluginClass == null) && (pluginClassName != null)) {
153             try {
154                 // load the plugin class object
155 pluginClass =
156                     digester.getClassLoader().loadClass(pluginClassName);
157             } catch(ClassNotFoundException JavaDoc cnfe) {
158                 throw new PluginException(
159                     "Unable to load class " + pluginClassName, cnfe);
160             }
161         }
162
163         if (ruleLoader == null) {
164             // the caller didn't provide a ruleLoader to the constructor,
165 // so get the plugin manager to "discover" one.
166 log.debug("Searching for ruleloader...");
167             ruleLoader = pm.findLoader(digester, id, pluginClass, properties);
168         } else {
169             log.debug("This declaration has an explicit ruleLoader.");
170         }
171         
172         if (debug) {
173             if (ruleLoader == null) {
174                 log.debug(
175                     "No ruleLoader found for plugin declaration"
176                     + " id [" + id + "]"
177                     + ", class [" + pluginClass.getClass().getName() + "].");
178             } else {
179                 log.debug(
180                     "RuleLoader of type [" + ruleLoader.getClass().getName()
181                     + "] associated with plugin declaration"
182                     + " id [" + id + "]"
183                     + ", class [" + pluginClass.getClass().getName() + "].");
184             }
185         }
186         
187         initialized = true;
188     }
189     
190     /**
191      * Attempt to load custom rules for the target class at the specified
192      * pattern.
193      * <p>
194      * On return, any custom rules associated with the plugin class have
195      * been loaded into the Rules object currently associated with the
196      * specified digester object.
197      */
198      
199     public void configure(Digester digester, String JavaDoc pattern)
200                           throws PluginException {
201         Log log = digester.getLogger();
202         boolean debug = log.isDebugEnabled();
203         if (debug) {
204             log.debug("configure being called!");
205         }
206         
207         if (!initialized) {
208             throw new PluginAssertionFailure("Not initialized.");
209         }
210
211         if (ruleLoader != null) {
212             ruleLoader.addRules(digester, pattern);
213         }
214     }
215 }
216
Popular Tags