1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.di;
17
18 import java.util.Set;
19
20 /**
21 * <p>
22 * Definition of an interface for objects that act as a registry for class
23 * loaders.
24 * </p>
25 * <p>
26 * In complex environments different class loaders can play an important role.
27 * Thus the dependency injection framework supports the registration of
28 * arbitrary class loaders; they are assigned a symbolic name. When a class is
29 * loaded, a class loader can be specified by the symbolic name it was
30 * registered.
31 * </p>
32 * <p>
33 * This interface provides access to the registered class loaders by their
34 * symbolic name. It can be used by components that need to load classes per
35 * reflection.
36 * </p>
37 *
38 * @author Oliver Heger
39 * @version $Id: ClassLoaderProvider.java 205 2012-01-29 18:29:57Z oheger $
40 */
41 public interface ClassLoaderProvider
42 {
43 /**
44 * Constant for the reserved name of the context class loader. If this
45 * constant is passed into the <code>getClassLoader()</code> method, the
46 * context class loader will automatically be used.
47 */
48 String CONTEXT_CLASS_LOADER = "CONTEXT";
49
50 /**
51 * Returns a reference to the class loader with the specified symbolic name.
52 * The passed in name can be <b>null</b>, then a default class loader will
53 * be returned. The constant <code>CONTEXT_CLASS_LOADER</code> can be
54 * passed in, too, for obtaining a reference to the context class loader. In
55 * all other cases the parameter is interpreted as the symbolic name of a
56 * registered class loader. If no class loader is found under this name, an
57 * exception will be thrown.
58 *
59 * @param name the name of the desired class loader
60 * @return the class loader for this name
61 * @throws InjectionException if the class loader cannot be resolved
62 */
63 ClassLoader getClassLoader(String name);
64
65 /**
66 * Returns the class specified by the given name. This is a convenience
67 * method that obtains the class loader specified by its symbolic name and
68 * immediately uses it for loading a class. The same naming conventions
69 * apply as described for the {@link #getClassLoader(String)} method.
70 * Occurring exceptions are re-thrown as runtime exceptions.
71 *
72 * @param name the name of the class to be loaded (must not be <b>null</b>)
73 * @param loaderRef the name, under which the desired class loader is
74 * registered (<b>null</b> for the default class loader)
75 * @return the loaded class
76 * @throws InjectionException if the class cannot be loaded
77 */
78 Class<?> loadClass(String name, String loaderRef);
79
80 /**
81 * Registers a <code>ClassLoader</code> under the given name. This class
82 * loader can later be accessed using the <code>getClassLoader()</code>
83 * method. If the class loader reference is <b>null</b>, the class loader
84 * with the given name will be unregistered.
85 *
86 * @param name a symbolic name for the class loader (must not be <b>null</b>)
87 * @param loader the class loader to be registered
88 * @throws IllegalArgumentException if the name is undefined
89 */
90 void registerClassLoader(String name, ClassLoader loader);
91
92 /**
93 * Returns the name of the default class loader.
94 *
95 * @return the name of the default class loader
96 * @see #setDefaultClassLoader(ClassLoader)
97 */
98 String getDefaultClassLoaderName();
99
100 /**
101 * Sets the name of the default class loader. It is possible to mark one of
102 * the registered class loaders as default class loader by passing its name
103 * to this method. Then this class loader will be used for all dynamic class
104 * loading operations for which no specific class loader name is specified.
105 * If this property was not set or the default class loader name is
106 * <b>null</b>, an implementation is free to return an arbitrary class
107 * loader - probably the one that loaded the implementation class.
108 *
109 * @param loaderName the name of the new default class loader
110 */
111 void setDefaultClassLoaderName(String loaderName);
112
113 /**
114 * Returns a set with the names of all registered class loaders.
115 *
116 * @return the names of all registered class loaders
117 */
118 Set<String> classLoaderNames();
119 }