/*
 * $Header: /cvshome/build/org.osgi.service.startlevel/src/org/osgi/service/startlevel/StartLevel.java,v 1.12 2006/03/14 01:21:38 hargrave Exp $
 * 
 * Copyright (c) OSGi Alliance (2002, 2005). All Rights Reserved.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.osgi.service.startlevel;

import org.osgi.framework.Bundle;

/**
 * The StartLevel service allows management agents to manage a start level
 * assigned to each bundle and the active start level of the Framework. There is
 * at most one StartLevel service present in the OSGi environment.
 * 
 * <p>
 * A start level is defined to be a state of execution in which the Framework
 * exists. StartLevel values are defined as unsigned integers with 0 (zero)
 * being the state where the Framework is not launched. Progressively higher
 * integral values represent progressively higher start levels. e.g. 2 is a
 * higher start level than 1.
 * <p>
 * Access to the StartLevel service is protected by corresponding
 * <code>ServicePermission</code>. In addition <code>AdminPermission</code>
 * is required to actually modify start level information.
 * <p>
 * Start Level support in the Framework includes the ability to control the
 * beginning start level of the Framework, to modify the active start level of
 * the Framework and to assign a specific start level to a bundle. How the
 * beginning start level of a Framework is specified is implementation
 * dependent. It may be a command line argument when invoking the Framework
 * implementation.
 * <p>
 * When the Framework is first started it must be at start level zero. In this
 * state, no bundles are running. This is the initial state of the Framework
 * before it is launched.
 * 
 * When the Framework is launched, the Framework will enter start level one and
 * all bundles which are assigned to start level one and are persistently marked
 * to be started are started as described in the <code>Bundle.start</code>
 * method. Within a start level, bundles are started in ascending order by
 * <code>Bundle.getBundleId</code>. The Framework will continue to increase
 * the start level, starting bundles at each start level, until the Framework
 * has reached a beginning start level. At this point the Framework has
 * completed starting bundles and will then fire a Framework event of type
 * <code>FrameworkEvent.STARTED</code> to announce it has completed its
 * launch.
 * 
 * <p>
 * The StartLevel service can be used by management bundles to alter the active
 * start level of the framework.
 * 
 * @version $Revision: 1.12 $
 */
public interface StartLevel {
	/**
	 * Return the active start level value of the Framework.
	 * 
	 * If the Framework is in the process of changing the start level this
	 * method must return the active start level if this differs from the
	 * requested start level.
	 * 
	 * @return The active start level value of the Framework.
	 */
	public int getStartLevel();

	/**
	 * Modify the active start level of the Framework.
	 * 
	 * <p>
	 * The Framework will move to the requested start level. This method will
	 * return immediately to the caller and the start level change will occur
	 * asynchronously on another thread.
	 * 
	 * <p>
	 * If the specified start level is higher than the active start level, the
	 * Framework will continue to increase the start level until the Framework
	 * has reached the specified start level, starting bundles at each start
	 * level which are persistently marked to be started as described in the
	 * <code>Bundle.start</code> method.
	 * 
	 * At each intermediate start level value on the way to and including the
	 * target start level, the framework must:
	 * <ol>
	 * <li>Change the active start level to the intermediate start level value.
	 * <li>Start bundles at the intermediate start level in ascending order by
	 * <code>Bundle.getBundleId</code>.
	 * </ol>
	 * When this process completes after the specified start level is reached,
	 * the Framework will fire a Framework event of type
	 * <code>FrameworkEvent.STARTLEVEL_CHANGED</code> to announce it has moved
	 * to the specified start level.
	 * 
	 * <p>
	 * If the specified start level is lower than the active start level, the
	 * Framework will continue to decrease the start level until the Framework
	 * has reached the specified start level stopping bundles at each start
	 * level as described in the <code>Bundle.stop</code> method except that
	 * their persistently recorded state indicates that they must be restarted
	 * in the future.
	 * 
	 * At each intermediate start level value on the way to and including the
	 * specified start level, the framework must:
	 * <ol>
	 * <li>Stop bundles at the intermediate start level in descending order by
	 * <code>Bundle.getBundleId</code>.
	 * <li>Change the active start level to the intermediate start level value.
	 * </ol>
	 * When this process completes after the specified start level is reached,
	 * the Framework will fire a Framework event of type
	 * <code>FrameworkEvent.STARTLEVEL_CHANGED</code> to announce it has moved
	 * to the specified start level.
	 * 
	 * <p>
	 * If the specified start level is equal to the active start level, then no
	 * bundles are started or stopped, however, the Framework must fire a
	 * Framework event of type <code>FrameworkEvent.STARTLEVEL_CHANGED</code>
	 * to announce it has finished moving to the specified start level. This
	 * event may arrive before the this method return.
	 * 
	 * @param startlevel The requested start level for the Framework.
	 * @throws IllegalArgumentException If the specified start level is less
	 *         than or equal to zero.
	 * @throws SecurityException If the caller does not have
	 *         <code>AdminPermission[System Bundle,STARTLEVEL]</code> and the Java runtime
	 *         environment supports permissions.
	 */
	public void setStartLevel(int startlevel);

	/**
	 * Return the assigned start level value for the specified Bundle.
	 * 
	 * @param bundle The target bundle.
	 * @return The start level value of the specified Bundle.
	 * @throws java.lang.IllegalArgumentException If the specified bundle has
	 *         been uninstalled.
	 */
	public int getBundleStartLevel(Bundle bundle);

	/**
	 * Assign a start level value to the specified Bundle.
	 * 
	 * <p>
	 * The specified bundle will be assigned the specified start level. The
	 * start level value assigned to the bundle will be persistently recorded by
	 * the Framework.
	 * 
	 * If the new start level for the bundle is lower than or equal to the
	 * active start level of the Framework, the Framework will start the
	 * specified bundle as described in the <code>Bundle.start</code> method
	 * if the bundle is persistently marked to be started. The actual starting
	 * of this bundle must occur asynchronously.
	 * 
	 * If the new start level for the bundle is higher than the active start
	 * level of the Framework, the Framework will stop the specified bundle as
	 * described in the <code>Bundle.stop</code> method except that the
	 * persistently recorded state for the bundle indicates that the bundle must
	 * be restarted in the future. The actual stopping of this bundle must occur
	 * asynchronously.
	 * 
	 * @param bundle The target bundle.
	 * @param startlevel The new start level for the specified Bundle.
	 * @throws IllegalArgumentException If the specified bundle has been
	 *         uninstalled or if the specified start level is less than or equal
	 *         to zero, or the specified bundle is the system bundle.
	 * @throws SecurityException If the caller does not have 
	 *         <code>AdminPermission[bundle,EXECUTE]</code> and the Java runtime
	 *         environment supports permissions.
	 */
	public void setBundleStartLevel(Bundle bundle, int startlevel);

	/**
	 * Return the initial start level value that is assigned to a Bundle when it
	 * is first installed.
	 * 
	 * @return The initial start level value for Bundles.
	 * @see #setInitialBundleStartLevel
	 */
	public int getInitialBundleStartLevel();

	/**
	 * Set the initial start level value that is assigned to a Bundle when it is
	 * first installed.
	 * 
	 * <p>
	 * The initial bundle start level will be set to the specified start level.
	 * The initial bundle start level value will be persistently recorded by the
	 * Framework.
	 * 
	 * <p>
	 * When a Bundle is installed via <code>BundleContext.installBundle</code>,
	 * it is assigned the initial bundle start level value.
	 * 
	 * <p>
	 * The default initial bundle start level value is 1 unless this method has
	 * been called to assign a different initial bundle start level value.
	 * 
	 * <p>
	 * Thie method does not change the start level values of installed bundles.
	 * 
	 * @param startlevel The initial start level for newly installed bundles.
	 * @throws IllegalArgumentException If the specified start level is less
	 *         than or equal to zero.
	 * @throws SecurityException If the caller does not have
	 *         <code>AdminPermission[System Bundle,STARTLEVEL]</code> and the Java runtime
	 *         environment supports permissions.
	 */
	public void setInitialBundleStartLevel(int startlevel);

	/**
	 * Return the persistent state of the specified bundle.
	 * 
	 * <p>
	 * This method returns the persistent state of a bundle. The persistent
	 * state of a bundle indicates whether a bundle is persistently marked to be
	 * started when it's start level is reached.
	 * 
	 * @param bundle The bundle for which to return the persistently started state.
	 * @return <code>true</code> if the bundle is persistently marked to be
	 *         started, <code>false</code> if the bundle is not persistently
	 *         marked to be started.
	 * @throws java.lang.IllegalArgumentException If the specified bundle has
	 *         been uninstalled.
	 */
	public boolean isBundlePersistentlyStarted(Bundle bundle);
}