StartLevel


1   /*
2    * $Header: /cvshome/build/org.osgi.service.startlevel/src/org/osgi/service/startlevel/StartLevel.java,v 1.19 2007/02/09 03:20:24 hargrave Exp $
3    * 
4    * Copyright (c) OSGi Alliance (2002, 2007). All Rights Reserved.
5    * 
6    * Licensed under the Apache License, Version 2.0 (the "License");
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *      http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  package org.osgi.service.startlevel;
20  
21  import org.osgi.framework.Bundle;
22  
23  /**
24   * The StartLevel service allows management agents to manage a start level
25   * assigned to each bundle and the active start level of the Framework. There is
26   * at most one StartLevel service present in the OSGi environment.
27   * 
28   * <p>
29   * A start level is defined to be a state of execution in which the Framework
30   * exists. StartLevel values are defined as unsigned integers with 0 (zero)
31   * being the state where the Framework is not launched. Progressively higher
32   * integral values represent progressively higher start levels. e.g. 2 is a
33   * higher start level than 1.
34   * <p>
35   * Access to the StartLevel service is protected by corresponding
36   * <code>ServicePermission</code>. In addition <code>AdminPermission</code>
37   * is required to actually modify start level information.
38   * <p>
39   * Start Level support in the Framework includes the ability to control the
40   * beginning start level of the Framework, to modify the active start level of
41   * the Framework and to assign a specific start level to a bundle. How the
42   * beginning start level of a Framework is specified is implementation
43   * dependent. It may be a command line argument when invoking the Framework
44   * implementation.
45   * <p>
46   * When the Framework is first started it must be at start level zero. In this
47   * state, no bundles are running. This is the initial state of the Framework
48   * before it is launched.
49   * 
50   * When the Framework is launched, the Framework will enter start level one and
51   * all bundles which are assigned to start level one and whose autostart setting
52   * indicates the bundle should be started are started as described in the
53   * <code>Bundle.start</code> method. The Framework will continue to increase
54   * the start level, starting bundles at each start level, until the Framework
55   * has reached a beginning start level. At this point the Framework has
56   * completed starting bundles and will then fire a Framework event of type
57   * <code>FrameworkEvent.STARTED</code> to announce it has completed its
58   * launch.
59   * 
60   * <p>
61   * Within a start level, bundles may be started in an order defined by the
62   * Framework implementation. This may be something like ascending
63   * <code>Bundle.getBundleId</code> order or an order based upon dependencies
64   * between bundles. A similar but reversed order may be used when stopping
65   * bundles within a start level.
66   * 
67   * <p>
68   * The StartLevel service can be used by management bundles to alter the active
69   * start level of the framework.
70   * 
71   * @version $Revision: 1.19 $
72   */
73  public interface StartLevel {
74      /**
75       * Return the active start level value of the Framework.
76       * 
77       * If the Framework is in the process of changing the start level this
78       * method must return the active start level if this differs from the
79       * requested start level.
80       * 
81       * @return The active start level value of the Framework.
82       */
83      public int getStartLevel();
84  
85      /**
86       * Modify the active start level of the Framework.
87       * 
88       * <p>
89       * The Framework will move to the requested start level. This method will
90       * return immediately to the caller and the start level change will occur
91       * asynchronously on another thread.
92       * 
93       * <p>
94       * If the specified start level is higher than the active start level, the
95       * Framework will continue to increase the start level until the Framework
96       * has reached the specified start level.
97       * 
98       * At each intermediate start level value on the way to and including the
99       * target start level, the Framework must:
100      * <ol>
101      * <li>Change the active start level to the intermediate start level value.
102      * <li>Start bundles at the intermediate start level whose autostart
103      * setting indicate they must be started. They are started as described in
104      * the {@link Bundle#start(int)} method using the
105      * {@link Bundle#START_TRANSIENT} option. The
106      * {@link Bundle#START_ACTIVATION_POLICY} option must also be used if
107      * {@link #isBundleActivationPolicyUsed(Bundle)} returns <code>true</code>
108      * for the bundle.
109      * </ol>
110      * When this process completes after the specified start level is reached,
111      * the Framework will fire a Framework event of type
112      * <code>FrameworkEvent.STARTLEVEL_CHANGED</code> to announce it has moved
113      * to the specified start level.
114      * 
115      * <p>
116      * If the specified start level is lower than the active start level, the
117      * Framework will continue to decrease the start level until the Framework
118      * has reached the specified start level.
119      * 
120      * At each intermediate start level value on the way to and including the
121      * specified start level, the framework must:
122      * <ol>
123      * <li>Stop bundles at the intermediate start level as described in the
124      * {@link Bundle#stop(int)} method using the {@link Bundle#STOP_TRANSIENT}
125      * option.
126      * <li>Change the active start level to the intermediate start level value.
127      * </ol>
128      * When this process completes after the specified start level is reached,
129      * the Framework will fire a Framework event of type
130      * <code>FrameworkEvent.STARTLEVEL_CHANGED</code> to announce it has moved
131      * to the specified start level.
132      * 
133      * <p>
134      * If the specified start level is equal to the active start level, then no
135      * bundles are started or stopped, however, the Framework must fire a
136      * Framework event of type <code>FrameworkEvent.STARTLEVEL_CHANGED</code>
137      * to announce it has finished moving to the specified start level. This
138      * event may arrive before this method return.
139      * 
140      * @param startlevel The requested start level for the Framework.
141      * @throws IllegalArgumentException If the specified start level is less
142      *         than or equal to zero.
143      * @throws SecurityException If the caller does not have
144      *         <code>AdminPermission[System Bundle,STARTLEVEL]</code> and the
145      *         Java runtime environment supports permissions.
146      */
147     public void setStartLevel(int startlevel);
148 
149     /**
150      * Return the assigned start level value for the specified Bundle.
151      * 
152      * @param bundle The target bundle.
153      * @return The start level value of the specified Bundle.
154      * @throws java.lang.IllegalArgumentException If the specified bundle has
155      *         been uninstalled.
156      */
157     public int getBundleStartLevel(Bundle bundle);
158 
159     /**
160      * Assign a start level value to the specified Bundle.
161      * 
162      * <p>
163      * The specified bundle will be assigned the specified start level. The
164      * start level value assigned to the bundle will be persistently recorded by
165      * the Framework.
166      * <p>
167      * If the new start level for the bundle is lower than or equal to the
168      * active start level of the Framework and the bundle's autostart setting
169      * indicates the bundle must be started, the Framework will start the
170      * specified bundle as described in the {@link Bundle#start(int)} method
171      * using the {@link Bundle#START_TRANSIENT} option. The
172      * {@link Bundle#START_ACTIVATION_POLICY} option must also be used if
173      * {@link #isBundleActivationPolicyUsed(Bundle)} returns <code>true</code>
174      * for the bundle. The actual starting of this bundle must occur
175      * asynchronously.
176      * <p>
177      * If the new start level for the bundle is higher than the active start
178      * level of the Framework, the Framework will stop the specified bundle as
179      * described in the {@link Bundle#stop(int)} method using the
180      * {@link Bundle#STOP_TRANSIENT} option. The actual stopping of this bundle
181      * must occur asynchronously.
182      * 
183      * @param bundle The target bundle.
184      * @param startlevel The new start level for the specified Bundle.
185      * @throws IllegalArgumentException If the specified bundle has been
186      *         uninstalled or if the specified start level is less than or equal
187      *         to zero, or the specified bundle is the system bundle.
188      * @throws SecurityException If the caller does not have
189      *         <code>AdminPermission[bundle,EXECUTE]</code> and the Java
190      *         runtime environment supports permissions.
191      */
192     public void setBundleStartLevel(Bundle bundle, int startlevel);
193 
194     /**
195      * Return the initial start level value that is assigned to a Bundle when it
196      * is first installed.
197      * 
198      * @return The initial start level value for Bundles.
199      * @see #setInitialBundleStartLevel
200      */
201     public int getInitialBundleStartLevel();
202 
203     /**
204      * Set the initial start level value that is assigned to a Bundle when it is
205      * first installed.
206      * 
207      * <p>
208      * The initial bundle start level will be set to the specified start level.
209      * The initial bundle start level value will be persistently recorded by the
210      * Framework.
211      * 
212      * <p>
213      * When a Bundle is installed via <code>BundleContext.installBundle</code>,
214      * it is assigned the initial bundle start level value.
215      * 
216      * <p>
217      * The default initial bundle start level value is 1 unless this method has
218      * been called to assign a different initial bundle start level value.
219      * 
220      * <p>
221      * Thie method does not change the start level values of installed bundles.
222      * 
223      * @param startlevel The initial start level for newly installed bundles.
224      * @throws IllegalArgumentException If the specified start level is less
225      *         than or equal to zero.
226      * @throws SecurityException If the caller does not have
227      *         <code>AdminPermission[System Bundle,STARTLEVEL]</code> and the
228      *         Java runtime environment supports permissions.
229      */
230     public void setInitialBundleStartLevel(int startlevel);
231 
232     /**
233      * Returns whether the specified bundle's autostart setting indicates the
234      * bundle must be started.
235      * <p>
236      * The autostart setting of a bundle indicates whether the bundle is to be
237      * started when its start level is reached.
238      * 
239      * @param bundle The bundle whose autostart setting is to be examined.
240      * @return <code>true</code> if the autostart setting of the bundle
241      *         indicates the bundle is to be started. <code>false</code>
242      *         otherwise.
243      * @throws java.lang.IllegalArgumentException If the specified bundle has
244      *         been uninstalled.
245      * @see Bundle#START_TRANSIENT
246      */
247     public boolean isBundlePersistentlyStarted(Bundle bundle);
248 
249     /**
250      * Returns whether the specified bundle's autostart setting indicates that
251      * the activation policy declared in the bundle's manifest must be used.
252      * <p>
253      * The autostart setting of a bundle indicates whether the bundle's declared
254      * activation policy is to be used when the bundle is started.
255      * 
256      * @param bundle The bundle whose autostart setting is to be examined.
257      * @return <code>true</code> if the bundle's autostart setting indicates
258      *         the activation policy declared in the manifest must be used.
259      *         <code>false</code> if the bundle must be eagerly activated.
260      * @throws java.lang.IllegalArgumentException If the specified bundle has
261      *         been uninstalled.
262      * @since 1.1
263      * @see Bundle#START_ACTIVATION_POLICY
264      */
265     public boolean isBundleActivationPolicyUsed(Bundle bundle);
266 }
267
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags