KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > openide > modules > ModuleInstall


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.openide.modules;
21
22 import org.openide.util.SharedClassObject;
23
24 /**
25 * Provides hooks for a custom module that may be inserted into NetBeans.
26 * If needed this class should be extended by the main class of a module.
27 *
28 * <p>Simple modules will likely not need a main class--just a few entries in the manifest file.
29 * Even modules with a main class need not do anything in it that is already covered by manifest entries;
30 * only additional special functionality need be handled here.
31 *
32 * <p>Specify this class in the manifest file with <code>OpenIDE-Module-Install</code>.
33 *
34 * <p>Modules wishing to keep state associated with the installation of the module
35 * may do so by implementing not only this class but also {@link java.io.Externalizable}.
36 * In this case, they are responsible for reading and writing their own state
37 * properly (probably using {@link java.io.ObjectOutput#writeObject} and {@link java.io.ObjectInput#readObject}).
38 * Note that state which is logically connected to the user's configuration of the module on
39 * a possibly project-specific basis should <em>not</em> be stored this way, but rather
40 * using a system option. (Even if this information is not to be displayed, it should
41 * still be stored as hidden properties of the system option, so as to be switched properly
42 * during project switches.)
43  * <strong>Storing externalizable state in a <code>ModuleInstall</code> is deprecated.</strong>
44 * @author Petr Hamernik, Jaroslav Tulach, Jesse Glick
45 */
46 public class ModuleInstall extends SharedClassObject {
47     private static final long serialVersionUID = -5615399519545301432L;
48
49     /** Called when a module is being considered for loading.
50      * (This would be before {@link #installed}, {@link #restored},
51      * or {@link #updated} are called.) If something is critically
52      * wrong with the module (missing ad-hoc dependency, missing
53      * license key, etc.) then <code>IllegalStateException</code>
54      * may be thrown to prevent it from being loaded (preferably
55      * with a localized annotation). The default implementation
56      * does nothing. The module cannot assume much about when this
57      * method will be called; specifically it cannot rely on layers
58      * or manifest sections to be ready, nor for the module's classloader
59      * to exist in the system class loader (so if loading bundles, icons,
60      * and so on, specifically pass in the class loader of the install
61      * class rather than relying on the default modules class loader).
62      * @since 1.24
63      */
64     public void validate() throws IllegalStateException JavaDoc {
65     }
66
67     /**
68      * Called when the module is first installed.
69      * Should perform whatever setup functions are required.
70      * The default implementation calls restored.
71      * <p>Typically, would do one-off functions, and then also call {@link #restored}.
72      * @deprecated Better to check specific aspects of the module's installation.
73      * For example, a globally installed module might be used in several
74      * user directories. Only the module itself can know whether its
75      * special installation tasks apply to some part of the global installation,
76      * or whether they apply to the module's usage in the current user directory.
77      * For this reason, implementing this method cannot be guaranteed
78      * to have useful effects.
79     */
80     public void installed() {
81         restored();
82     }
83
84     /**
85      * Called when an already-installed module is restored (during startup).
86      * Should perform whatever initializations are required.
87      * <p>Note that it is possible for module code to be run before this method
88      * is called, and that code must be ready nonetheless. For example, data loaders
89      * might be asked to recognize a file before the module is "restored". For this
90      * reason, but more importantly for general performance reasons, modules should
91      * avoid doing anything here that is not strictly necessary - often by moving
92      * initialization code into the place where the initialization is actually first
93      * required (if ever). This method should serve as a place for tasks that must
94      * be run once during every startup, and that cannot reasonably be put elsewhere.
95      * <p>Basic programmatic services are available to the module at this stage -
96      * for example, its class loader is ready for general use, any objects registered
97      * declaratively to lookup (e.g. system options or services) are ready to be
98      * queried, and so on.
99      */
100     public void restored() {
101     }
102
103     /**
104      * Called when the module is loaded and the version is higher than
105      * by the previous load
106      * The default implementation calls {@link #restored}.
107      * @param release The major release number of the <B>old</B> module code name or -1 if not specified.
108      * @param specVersion The specification version of the this <B>old</B> module.
109      * @deprecated Better to check specific aspects of the module's installation.
110      * For example, a globally installed module might be used in several
111      * user directories. Only the module itself can know whether its
112      * special installation tasks apply to some part of the global installation,
113      * or whether they apply to the module's usage in the current user directory.
114      * For this reason, implementing this method cannot be guaranteed
115      * to have useful effects.
116     */
117     public void updated(int release, String JavaDoc specVersion) {
118         restored();
119     }
120
121     /**
122      * Called when the module is uninstalled (from a running NetBeans instance).
123      * Should remove whatever functionality that it had registered.
124     */
125     public void uninstalled() {
126     }
127
128     /**
129      * Called when NetBeans is about to exit. The default implementation returns <code>true</code>.
130      * The module may cancel the exit if it is not prepared to be shut down.
131     * @return <code>true</code> if it is ok to exit
132     */
133     public boolean closing() {
134         return true;
135     }
136
137     /**
138      * Called when all modules agreed with closing and NetBeans will be closed.
139     */
140     public void close() {
141     }
142
143     protected boolean clearSharedData() {
144         return false;
145     }
146 }
147
Popular Tags