IInstallHandler


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.update.core;
12  
13  import org.eclipse.core.runtime.CoreException;
14  import org.eclipse.core.runtime.IProgressMonitor;
15  
16  /**
17   * Custom install handler.
18   * Custom install handlers can optionally be associated with a feature.
19   * The actual install handler implementation can be physically delivered
20   * as part of the feature package, or can already be installed on the client
21   * machine and registered via the <code>org.eclipse.update.core.installHandlers</code>
22   * extension point. The install handler methods are called at predetermined
23   * point during update actions.
24   * <p>
25   * Clients may implement this interface. However, in most cases clients should 
26   * directly subclass the provided implementation of this interface.
27   * </p>
28   * <p>
29   * <b>Note:</b> This class/interface is part of an interim API that is still under development and expected to
30   * change significantly before reaching stability. It is being made available at this early stage to solicit feedback
31   * from pioneering adopters on the understanding that any code that uses this API will almost certainly be broken
32   * (repeatedly) as the API evolves.
33   * </p>
34   * @see org.eclipse.update.core.BaseInstallHandler
35   * @since 2.0
36   */
37  public interface IInstallHandler {
38  
39      /**
40       * Indicates the handler is being initialized for feature install.
41       * @since 2.0
42       */
43      public static final int HANDLER_ACTION_INSTALL = 1;
44  
45      /**
46       * Indicates the handler is being initialized for feature configure.
47       * @since 2.0
48       */
49      public static final int HANDLER_ACTION_CONFIGURE = 2;
50  
51      /**
52       * Indicates the handler is being initialized for feature unconfigure.
53       * @since 2.0
54       */
55      public static final int HANDLER_ACTION_UNCONFIGURE = 3;
56  
57      /**
58       * Indicates the handler is being initialized for feature uninstall.
59       * @since 2.0
60       */
61      public static final int HANDLER_ACTION_UNINSTALL = 4;
62  
63      /**
64       * Initialize the install handler.
65       * Install handlers are always constructed using the default constructor.
66       * The are initialized immediately following construction.
67       * 
68       * @param type update action type
69       * @param feature the target of the action
70       * @param entry model entry that defines this handler
71       * @param monitor optional progress monitor, can be <code>null</code>
72       * @exception CoreException
73       * @since 2.0
74       */
75      public void initialize(
76          int type,
77          IFeature feature,
78          IInstallHandlerEntry entry,
79          InstallMonitor monitor)
80          throws CoreException;
81  
82      /**
83       * Called at the start of the install action. At this point, no install
84       * processing has taken place.
85       * 
86       * @see #HANDLER_ACTION_INSTALL
87       * @exception CoreException terminates the action
88       * @since 2.0
89       */
90      public void installInitiated() throws CoreException;
91  
92      /**
93       * Called after files corresponding to plug-in entries have been downloaded,
94       * but before they are actully unpacked and installed.
95       * 
96       * @see #HANDLER_ACTION_INSTALL
97       * @param plugins downloaded plug-in entries. Note this may be a subset
98       * of the plug-ins actually references by the feature.
99       * @exception CoreException terminates the action
100      * @since 2.0
101      */
102     public void pluginsDownloaded(IPluginEntry[] plugins) throws CoreException;
103 
104     /**
105      * Called after files corresponding to non-plug-in entries have been 
106      * downloaded. The custom install handler can perform any custom
107      * verification of the non-plug-in entries (these are not interpreted
108      * in any way by the platform (beyond downloading)).
109      * 
110      * @see #HANDLER_ACTION_INSTALL
111      * @param nonPluginData downloaded non-plug-in entries.
112      * @param listener verification listener, may be <code>null</code>.
113      * @exception CoreException terminates the action
114      * @since 2.0
115      */
116     public void nonPluginDataDownloaded(
117         INonPluginEntry[] nonPluginData,
118         IVerificationListener listener)
119         throws CoreException;
120 
121     /**
122      * Called after the feature files and any downloaded plug-ins have
123      * been installed. Typically this is the point where the custom
124      * install handler can install any non-plug-in entries (these are not 
125      * interpreted in any way by the platform (beyond downloading)).
126      * 
127      * @see #HANDLER_ACTION_INSTALL
128      * @param consumer content consumer for the feature. The install handler
129      * can choose to use this consumer to install the non-plug-in data,
130      * or can handle the data in any other way. If using the consumer,
131      * the install handler should only call 
132      * @see IFeatureContentConsumer#store(ContentReference, IProgressMonitor)
133      * and @see IFeatureContentConsumer#open(INonPluginEntry)
134      * methods of the consumer. 
135      * @exception CoreException terminates the action
136      * @since 2.0
137      */
138     public void completeInstall(IFeatureContentConsumer consumer)
139         throws CoreException;
140 
141     /**
142      * Called at the end of the install action.
143      * 
144      * @see #HANDLER_ACTION_INSTALL
145      * @param success indicates action success. 
146      * @exception CoreException terminates the action
147      * @since 2.0
148      */
149     public void installCompleted(boolean success) throws CoreException;
150 
151     /**
152      * Called at the start of the configure action
153      * 
154      * @see #HANDLER_ACTION_CONFIGURE
155      * @exception CoreException terminates the action
156      * @since 2.0
157      */
158     public void configureInitiated() throws CoreException;
159 
160     /**
161      * Called after the feature has been configured. The install handler
162      * should perform any completion tasks. No arguments are passed
163      * to the method. If needed, the install handler can use arguments
164      * passed on the initialization call.
165      * 
166      * @see #HANDLER_ACTION_CONFIGURE
167      * @exception CoreException terminates the action
168      * @since 2.0
169      */
170     public void completeConfigure() throws CoreException;
171 
172     /**
173      * Called at the end of the configure action.
174      * 
175      * @see #HANDLER_ACTION_CONFIGURE
176      * @param success indicates action success. 
177      * @exception CoreException terminates the action
178      * @since 2.0
179      */
180     public void configureCompleted(boolean success) throws CoreException;
181 
182     /**
183      * Called at the start of the unconfigure action
184      * 
185      * @see #HANDLER_ACTION_UNCONFIGURE
186      * @exception CoreException terminates the action
187      * @since 2.0
188      */
189     public void unconfigureInitiated() throws CoreException;
190 
191     /**
192      * Called after the feature has been unconfigured. The install handler
193      * should perform any completion tasks. No arguments are passed
194      * to the method. If needed, the install handler can use arguments
195      * passed on the initialization call.
196      * 
197      * @see #HANDLER_ACTION_UNCONFIGURE
198      * @exception CoreException terminates the action
199      * @since 2.0
200      */
201     public void completeUnconfigure() throws CoreException;
202 
203     /**
204      * Called at the end of the unconfigure action.
205      * 
206      * @see #HANDLER_ACTION_UNCONFIGURE
207      * @param success indicates action success. 
208      * @exception CoreException terminates the action
209      * @since 2.0
210      */
211     public void unconfigureCompleted(boolean success) throws CoreException;
212 
213     /**
214      * Called at the start of the uninstall action
215      * 
216      * @see #HANDLER_ACTION_UNINSTALL
217      * @exception CoreException terminates the action
218      * @since 2.0
219      */
220     public void uninstallInitiated() throws CoreException;
221 
222     /**
223      * Called after the feature has been uninstalled. The install handler
224      * should perform any completion tasks. No arguments are passed
225      * to the method. If needed, the install handler can use arguments
226      * passed on the initialization call. Note, that at this point
227      * the feature files and any unreferenced plug-ins have been
228      * removed.
229      * 
230      * @see #HANDLER_ACTION_UNINSTALL
231      * @exception CoreException terminates the action
232      * @since 2.0
233      */
234     public void completeUninstall() throws CoreException;
235 
236     /**
237      * Called at the end of the uninstall action.
238      * 
239      * @see #HANDLER_ACTION_UNINSTALL
240      * @param success indicates action success. 
241      * @exception CoreException terminates the action
242      * @since 2.0
243      */
244     public void uninstallCompleted(boolean success) throws CoreException;
245 }
246
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags