KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > ungoverned > moduleloader > SearchPolicy


1 /*
2  * ModuleLoader - A generic, policy-driven class loader.
3  * Copyright (c) 2004, Richard S. Hall
4  * All rights reserved.
5  *
6  * Redistribution and use in source and binary forms, with or without
7  * modification, are permitted provided that the following conditions
8  * are met:
9  *
10  * * Redistributions of source code must retain the above copyright
11  * notice, this list of conditions and the following disclaimer.
12  * * Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in
14  * the documentation and/or other materials provided with the
15  * distribution.
16  * * Neither the name of the ungoverned.org nor the names of its
17  * contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
25  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
26  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
30  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  *
32  * Contact: Richard S. Hall (heavy@ungoverned.org)
33  * Contributor(s):
34  *
35 **/
36 package org.ungoverned.moduleloader;
37
38 import java.net.URL JavaDoc;
39
40 /**
41  * <p>
42  * This interface represents a policy to define the most basic behavior
43  * of how classes, resources, and native libraries within a specific instance
44  * of <tt>ModuleManager</tt> are found. A <tt>ModuleManager</tt> manages a set of
45  * <tt>Module</tt>s, each of which is a potential source of classes, resources,
46  * and native libraries. The search policy makes it possible to consult these
47  * sources without hard-coding assumptions about application behavior
48  * or structure. Applicaitons inject their own specific class loading policy
49  * by creating a custom search policy or by selecting a pre-existing search
50  * policy that matches their needs.
51  * </p>
52  * <p>
53  * The search policy is used by <tt>ModuleClassLoader</tt>, of which, there
54  * is one per <tt>Module</tt> within a given <tt>ModuleManager</tt> instance.
55  * The search policy is consulted by the <tt>ModuleClassLoader</tt> whenever
56  * there is a request for a class, resource, or native library. The search
57  * policy will generally search other modules in an application-specific
58  * way in order to find the requested item; for example, an application may
59  * use a policy where module's may import from one another. If the search
60  * policy provides an answer, then the <tt>ModuleClassLoader</tt> will use
61  * this to answer the originating request.
62  * </p>
63  * <p>
64  * <b><i>Important:</i></b> The search policy <i>searches</i> modules in
65  * some application-specific manner in order to find a class or resource.
66  * This <i>search</i> is instigated, either directly or indirectly, by calls
67  * to <tt>ModuleClassLoader.loadClass()</tt> and <tt>ModuleClassLoader.getResource()</tt>,
68  * respectively. In order for the search policy to load a class or resource,
69  * it must <b>not</b> use <tt>ModuleClassLoader.loadClass()</tt> or
70  * <tt>ModuleClassLoader.getResource()</tt> again, because this would result
71  * in an infinite loop. Instead, the <tt>ModuleClassLoader</tt> offers the
72  * the methods <tt>ModuleClassLoader.searchForClass()</tt> and
73  * <tt>ModuleClassLoader.searchForResource()</tt> to search a given module
74  * and to avoid an infinite loop.
75  * </p>
76  * <pre>
77  * ...
78  * public Class findClass(Module module, String name)
79  * {
80  * Module[] modules = m_mgr.getModules();
81  * for (int i = 0; i < modules.length; i++)
82  * {
83  * try {
84  * Class clazz = modules[i].getClassLoader().searchForClass(name);
85  * if (clazz != null)
86  * {
87  * return clazz;
88  * }
89  * } catch (Throwable th) {
90  * }
91  * }
92  *
93  * return null;
94  * }
95  * ...
96  * </pre>
97  * <p>
98  * In the above code, the search policy "exhaustively" searches every module in the
99  * <tt>ModuleManager</tt> to find the requested resource. Note that this policy
100  * will also search the module that originated the request, which is not totally
101  * necessary since returning <tt>null</tt> will cause the <tt>ModuleClassLoader</tt>
102  * to search the originating module's <tt>ResourceSource</tt>s.
103  * </p>
104 **/
105 public interface SearchPolicy
106 {
107     /**
108      * <p>
109      * This method is called once by the <tt>ModuleManager</tt> to
110      * give the search policy instance a reference to its associated
111      * module manager. This method should be implemented such that
112      * it cannot be called twice; calling this method a second time
113      * should produce an illegal state exception.
114      * </p>
115      * @param mgr the module manager associated with this search policy.
116      * @throws java.lang.IllegalStateException if the method is called
117      * more than once.
118     **/
119     public void setModuleManager(ModuleManager mgr)
120         throws IllegalStateException JavaDoc;
121
122     /**
123      * <p>
124      * This method tries to find the specified class for the specified
125      * module. How the class is found or whether it is actually retrieved
126      * from the specified module is dependent upon the implementation. The
127      * default <tt>ModuleClassLoader.loadClass()</tt> method does not do
128      * any searching of its own, it merely calls <tt>ClassLoader.resolveClass()</tt>
129      * on the class returned by this method.
130      * </p>
131      * <p>
132      * This method may return <tt>null</tt> or throw an exception if the
133      * specified class is not found. Whether a specific search policy
134      * implementation should do one or the other depends on the details
135      * of the specific search policy. The <tt>ModuleClassLoader</tt>
136      * first delegates to this method and then to the local resource
137      * sources of the module. If this method returns null, then the local
138      * resource sources will be searched. On the other hand, if this method
139      * throws an exception, then the local resource sources will not be
140      * searched.
141      * </p>
142      * <p>
143      * <b>Important:</b> If the implementation of this method delegates
144      * the class loading to a <tt>ModuleClassLoader</tt> of another module,
145      * then it should <b>not</b> use the method <tt>ModuleClassLoader.loadClass()</tt>
146      * to load the class; it should use <tt>ModuleClassLoader.searchForClass()</tt>
147      * instead. This is necessary to eliminate an infinite loop that would
148      * occur otherwise. Also, with respect to the <tt>ModuleLoader</tt> framework,
149      * this method will only be called by a single thread at a time and is only
150      * intended to be called by <tt>ModuleClassLoader.loadClass()</tt>.
151      * </p>
152      * @param parent the parent class loader of the delegating class loader.
153      * @param module the target module that is loading the class.
154      * @param name the name of the class being loaded.
155      * @return the class if found, <tt>null</tt> otherwise.
156      * @throws java.lang.ClassNotFoundException if the class could not be
157      * found and the entire search operation should fail.
158     **/
159     public Class JavaDoc findClass(Module module, String JavaDoc name)
160         throws ClassNotFoundException JavaDoc;
161
162     /**
163      * <p>
164      * This method tries to find the specified resource for the specified
165      * module. How the resource is found or whether it is actually retrieved
166      * from the specified module is dependent upon the implementation. The
167      * default <tt>ModuleClassLoader.getResource()</tt> method does not do
168      * any searching on its own.
169      * </p>
170      * <p>
171      * This method may return <tt>null</tt> or throw an exception if the
172      * specified resource is not found. Whether a specific search policy
173      * implementation should do one or the other depends on the details
174      * of the specific search policy. The <tt>ModuleClassLoader</tt>
175      * first delegates to this method and then to the local resource
176      * sources of the module. If this method returns null, then the local
177      * resource sources will be searched. On the other hand, if this method
178      * throws an exception, then the local resource sources will not be
179      * searched.
180      * </p>
181      * <p>
182      * <b>Important:</b> If the implementation of this method delegates
183      * the resource loading to a <tt>ModuleClassLoader</tt> of another module,
184      * then it should not use the method <tt>ModuleClassLoader.getResource()</tt>
185      * to get the resource; it should use <tt>ModuleClassLoader.searchForResource()</tt>
186      * instead. This is necessary to eliminate an infinite loop that would
187      * occur otherwise. Also, with respect to the <tt>ModuleLoader</tt> framework,
188      * this method will only be called by a single thread at a time and is not
189      * intended to be called directly.
190      * </p>
191      * @param parent the parent class loader of the delegating class loader.
192      * @param module the target module that is loading the resource.
193      * @param name the name of the resource being loaded.
194      * @return a <tt>URL</tt> to the resource if found, <tt>null</tt> otherwise.
195      * @throws org.ungoverned.moduleloader.ResourceNotFoundException if the
196      * resource could not be found and the entire search operation
197      * should fail.
198     **/
199     public URL JavaDoc findResource(Module module, String JavaDoc name)
200         throws ResourceNotFoundException;
201 }
Popular Tags