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  ;
23  import java.io.IOException  ;
24  import java.util.List  ;
25  import java.util.Set  ;
26  import java.util.jar.JarFile  ;
27  import java.util.jar.Manifest  ;
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  <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  <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  <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  <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  <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   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   loadManifest(File   jar) throws IOException   {
141         JarFile   jarFile = new JarFile  (jar, false);
142         try {
143             Manifest   m = jarFile.getManifest();
144             if (m == null) throw new IOException  ("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   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  [] 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   pkg) {
181         return false;
182     }
183 
184 }
185
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags