KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > ModuleInstaller


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */

19
20 package org.netbeans;
21
22 import java.io.File JavaDoc;
23 import java.io.IOException JavaDoc;
24 import java.util.List JavaDoc;
25 import java.util.Set JavaDoc;
26 import java.util.jar.JarFile JavaDoc;
27 import java.util.jar.Manifest JavaDoc;
28 import org.openide.modules.Dependency;
29
30 /** Responsible for actually installing the contents of module JARs into the IDE.
31  * While the manager tracks which modules are enabled and their dependencies,
32  * the installer actually understands the manifest contents and is able to
33  * add layers, sections, etc. to the IDE's runtime.
34  * @author Jesse Glick
35  */

36 public abstract class ModuleInstaller {
37     
38     /** No-op constructor for subclasses. */
39     protected ModuleInstaller() {}
40     
41     /** Called to ensure that a module is valid to be installed, before continuing.
42      * Should examine the manifest and check its syntax (may keep cached parse
43      * information about that syntax). When this method is called, the module's
44      * classloader should be ready for use, but the system classloader will not
45      * yet contain it. It may (but need not) try to load
46      * mentioned resources from that classloader in order to catch errors early
47      * on. For some resources it may be preferable to load them lazily.
48      * If the installer indicates the module is invalid, it will not be installed.
49      * InvalidException thrown from here must include a reference to the module.
50      */

51     public abstract void prepare(Module m) throws InvalidException;
52     
53     /** Called when a module is being uninstalled and runtime information
54      * about it is no longer needed.
55      * The installer should remove any associated cache entries and try
56      * to release anything that might have been loaded with the module's
57      * classloader. The classloader may still be valid at this point but
58      * better not to use it.
59      */

60     public abstract void dispose(Module m);
61     
62     /** Actually load some modules into the IDE.
63      * They will all have been prepared already, and their classloaders
64      * will be contained in the system classloader.
65      * It is expected to handle any resultant exceptions appropriately
66      * (e.g. skipping over a module, or skipping over that piece of a module).
67      * Where load order is significant, items should be installed in the order
68      * supplied: starting with basic modules and ending with dependent modules.
69      * Installers may choose to install all resources of a certain type (e.g.
70      * layers) from every module, then all of the next type, etc., for purposes
71      * of efficiency.
72      * Note that "loading" could really mean installing or restoring or upgrading,
73      * depending on module history.
74      */

75     public abstract void load(List JavaDoc<Module> modules);
76     
77     /** Unload some modules from the IDE.
78      * Where unload order is significant, items should be uninstalled in the order
79      * supplied: starting with dependent modules and ending with basic modules.
80      * Module classloaders will still be in the system classloader.
81      */

82     public abstract void unload(List JavaDoc<Module> modules);
83     
84     /** Ask to shut down the IDE from a set of modules.
85      * Will begin with dependent and end with basic modules.
86      */

87     public abstract boolean closing(List JavaDoc<Module> modules);
88     
89     /** Notify modules the IDE will be shut down.
90      * Will begin with dependent and end with basic modules.
91      */

92     public abstract void close(List JavaDoc<Module> modules);
93     
94     /** Optionally refine the dependencies for a module.
95      * For example, an installer might decide to automatically add a dependency
96      * on a "stock" library module for all client modules meeting some criterion.
97      * The default implementation makes no change.
98      * @param m a module to possibly refine dependencies for; overriders must not call
99      * getDependencies on this module nor attempt to directly change it
100      * in any way; overriders may ask for module code name, version, etc.
101      * @param dependencies a set of Dependency's; mutable, entries may be added or removed
102      * during the dynamic scope of this call
103      * @since org.netbeans.core/1 1.2
104      */

105     public void refineDependencies(Module m, Set JavaDoc<Dependency> dependencies) {}
106     
107     /** Optionally mask package use in a module classloader.
108      * For example, an installer might decide that a module may not use a
109      * package in the application classpath because it is an unguaranteed
110      * implementation package and the module has not explicitly requested
111      * to use it.
112      * <p>The module system automatically excludes improper access
113      * to non-public packages (as declared via <code>OpenIDE-Module-Public-Packages</code>)
114      * and cross-module access to the <code>META-INF/</code> directory.
115      * <p>The default implementation of this method permits all other
116      * package delegation.
117      * @param m the module requesting use of a given package
118      * @param parent the module which might possibly supply that package, or
119      * null if the possible provider is not a module (i.e. application
120      * classpath)
121      * @param pkg the name of the package in use, in the form "org/netbeans/modules/foo/"
122      * (i.e. slash-separated and ending in a slash as well)
123      * @since org.netbeans.core/1 1.3
124      */

125     public boolean shouldDelegateResource(Module m, Module parent, String JavaDoc pkg) {
126         return true;
127     }
128     
129     /** Scan a disabled module JAR file for its manifest contents.
130      * Subclasses may implement this efficiently, e.g. to use a special cache.
131      * <p>The default implementation simply opens the JAR and gets its manifest
132      * using the standard JRE calls.
133      * <p>Never called for reloadable JARs.
134      * @param jar a module JAR to open
135      * @return its manifest
136      * @throws IOException if the JAR cannot be opened or does not have a manifest at all
137      * @since org.netbeans.core/1 1.5
138      * @see "#26786"
139      */

140     public Manifest JavaDoc loadManifest(File JavaDoc jar) throws IOException JavaDoc {
141         JarFile JavaDoc jarFile = new JarFile JavaDoc(jar, false);
142         try {
143             Manifest JavaDoc m = jarFile.getManifest();
144             if (m == null) throw new IOException JavaDoc("No manifest found in " + jar); // NOI18N
145
return m;
146         } finally {
147             jarFile.close();
148         }
149     }
150     
151     /** Permit a module installer to add extra parent classloaders for a module.
152      * Called during enablement of a module.
153      * The default implementation does nothing.
154      * @param m a module which is about to be enabled
155      * @param parents current list of <code>ClassLoader</code> parents; may be mutated (appended to)
156      * @since org.netbeans.core/1 > 1.6
157      * @see "#27853"
158      */

159     public void refineClassLoader(Module m, List JavaDoc parents) {
160         // do nothing
161
}
162
163     /** Optionally adds additional token for the module.
164      * @param m the module to add token to
165      * @return null or list of tokens this module provides
166      * @since org.netbeans.core/1 > 1.25
167      * @see "#46833"
168      */

169     public String JavaDoc[] refineProvides (Module m) {
170         return null;
171     }
172     
173     /** Is this package special in that the package domain cache should be disabled for it?
174      * The result must never change between subsequent calls for the same argument.
175      * The default implementation always says no.
176      * @param pkg a package in the form "org/netbeans/modules/foo/"
177      * @return true if this package might be split across modules, otherwise false
178      * @since org.netbeans.core/1 > 1.7
179      */

180     public boolean isSpecialResource(String JavaDoc pkg) {
181         return false;
182     }
183
184 }
185
Popular Tags