001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans;
043:
044: import java.io.File;
045: import java.io.IOException;
046: import java.util.List;
047: import java.util.Set;
048: import java.util.jar.JarFile;
049: import java.util.jar.Manifest;
050: import org.openide.modules.Dependency;
051:
052: /** Responsible for actually installing the contents of module JARs into the IDE.
053: * While the manager tracks which modules are enabled and their dependencies,
054: * the installer actually understands the manifest contents and is able to
055: * add layers, sections, etc. to the IDE's runtime.
056: * @author Jesse Glick
057: */
058: public abstract class ModuleInstaller {
059:
060: /** No-op constructor for subclasses. */
061: protected ModuleInstaller() {
062: }
063:
064: /** Called to ensure that a module is valid to be installed, before continuing.
065: * Should examine the manifest and check its syntax (may keep cached parse
066: * information about that syntax). When this method is called, the module's
067: * classloader should be ready for use, but the system classloader will not
068: * yet contain it. It may (but need not) try to load
069: * mentioned resources from that classloader in order to catch errors early
070: * on. For some resources it may be preferable to load them lazily.
071: * If the installer indicates the module is invalid, it will not be installed.
072: * InvalidException thrown from here must include a reference to the module.
073: */
074: public abstract void prepare(Module m) throws InvalidException;
075:
076: /** Called when a module is being uninstalled and runtime information
077: * about it is no longer needed.
078: * The installer should remove any associated cache entries and try
079: * to release anything that might have been loaded with the module's
080: * classloader. The classloader may still be valid at this point but
081: * better not to use it.
082: */
083: public abstract void dispose(Module m);
084:
085: /** Actually load some modules into the IDE.
086: * They will all have been prepared already, and their classloaders
087: * will be contained in the system classloader.
088: * It is expected to handle any resultant exceptions appropriately
089: * (e.g. skipping over a module, or skipping over that piece of a module).
090: * Where load order is significant, items should be installed in the order
091: * supplied: starting with basic modules and ending with dependent modules.
092: * Installers may choose to install all resources of a certain type (e.g.
093: * layers) from every module, then all of the next type, etc., for purposes
094: * of efficiency.
095: * Note that "loading" could really mean installing or restoring or upgrading,
096: * depending on module history.
097: */
098: public abstract void load(List<Module> modules);
099:
100: /** Unload some modules from the IDE.
101: * Where unload order is significant, items should be uninstalled in the order
102: * supplied: starting with dependent modules and ending with basic modules.
103: * Module classloaders will still be in the system classloader.
104: */
105: public abstract void unload(List<Module> modules);
106:
107: /** Ask to shut down the IDE from a set of modules.
108: * Will begin with dependent and end with basic modules.
109: */
110: public abstract boolean closing(List<Module> modules);
111:
112: /** Notify modules the IDE will be shut down.
113: * Will begin with dependent and end with basic modules.
114: */
115: public abstract void close(List<Module> modules);
116:
117: /** Optionally refine the dependencies for a module.
118: * For example, an installer might decide to automatically add a dependency
119: * on a "stock" library module for all client modules meeting some criterion.
120: * The default implementation makes no change.
121: * @param m a module to possibly refine dependencies for; overriders must not call
122: * getDependencies on this module nor attempt to directly change it
123: * in any way; overriders may ask for module code name, version, etc.
124: * @param dependencies a set of Dependency's; mutable, entries may be added or removed
125: * during the dynamic scope of this call
126: * @since org.netbeans.core/1 1.2
127: */
128: public void refineDependencies(Module m,
129: Set<Dependency> dependencies) {
130: }
131:
132: /** Optionally mask package use in a module classloader.
133: * For example, an installer might decide that a module may not use a
134: * package in the application classpath because it is an unguaranteed
135: * implementation package and the module has not explicitly requested
136: * to use it.
137: * <p>The module system automatically excludes improper access
138: * to non-public packages (as declared via <code>OpenIDE-Module-Public-Packages</code>)
139: * and cross-module access to the <code>META-INF/</code> directory.
140: * <p>The default implementation of this method permits all other
141: * package delegation.
142: * @param m the module requesting use of a given package
143: * @param parent the module which might possibly supply that package, or
144: * null if the possible provider is not a module (i.e. application
145: * classpath)
146: * @param pkg the name of the package in use, in the form "org/netbeans/modules/foo/"
147: * (i.e. slash-separated and ending in a slash as well)
148: * @since org.netbeans.core/1 1.3
149: */
150: public boolean shouldDelegateResource(Module m, Module parent,
151: String pkg) {
152: return true;
153: }
154:
155: /** Scan a disabled module JAR file for its manifest contents.
156: * Subclasses may implement this efficiently, e.g. to use a special cache.
157: * <p>The default implementation simply opens the JAR and gets its manifest
158: * using the standard JRE calls.
159: * <p>Never called for reloadable JARs.
160: * @param jar a module JAR to open
161: * @return its manifest
162: * @throws IOException if the JAR cannot be opened or does not have a manifest at all
163: * @since org.netbeans.core/1 1.5
164: * @see "#26786"
165: */
166: public Manifest loadManifest(File jar) throws IOException {
167: JarFile jarFile = new JarFile(jar, false);
168: try {
169: Manifest m = jarFile.getManifest();
170: if (m == null)
171: throw new IOException("No manifest found in " + jar); // NOI18N
172: return m;
173: } finally {
174: jarFile.close();
175: }
176: }
177:
178: /** Permit a module installer to add extra parent classloaders for a module.
179: * Called during enablement of a module.
180: * The default implementation does nothing.
181: * @param m a module which is about to be enabled
182: * @param parents current list of <code>ClassLoader</code> parents; may be mutated (appended to)
183: * @since org.netbeans.core/1 > 1.6
184: * @see "#27853"
185: */
186: public void refineClassLoader(Module m, List parents) {
187: // do nothing
188: }
189:
190: /** Optionally adds additional token for the module.
191: * @param m the module to add token to
192: * @return null or list of tokens this module provides
193: * @since org.netbeans.core/1 > 1.25
194: * @see "#46833"
195: */
196: public String[] refineProvides(Module m) {
197: return null;
198: }
199:
200: }
|