content: /*
   * Copyright (c) OSGi Alliance (2009, 2010). 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.jmx.framework;
  
  import java.io.IOException;
  import javax.management.openmbean.CompositeData;
  import javax.management.openmbean.CompositeType;
  import javax.management.openmbean.SimpleType;
  
  import org.osgi.jmx.Item;
  import org.osgi.jmx.JmxConstants;
  
  /**
   * The FrameworkMbean provides mechanisms to exert control over the framework.
   * For many operations, it provides a batch mechanism to avoid excessive message
   * passing when interacting remotely.
   *
   * @version $Revision$
   * @ThreadSafe
   */
  public interface FrameworkMBean {
  	/**
  	 * The fully qualified object name of this mbean.
  	 */
  	String			OBJECTNAME						= JmxConstants.OSGI_CORE
  															+ ":type=framework,version=1.7";
  
  	/**
  	 * The SUCCESS, used in {@link #SUCCESS_ITEM}.
  	 */
  	String			SUCCESS							= "Success";
  
  	/**
  	 * The item that indicates if this operation was successful. The key is
  	 * {@link #SUCCESS} and the type is {@link SimpleType#BOOLEAN}. It is used
  	 * in {@link #BATCH_ACTION_RESULT_TYPE} and
  	 * {@link #BATCH_INSTALL_RESULT_TYPE}.
  	 */
  	Item			SUCCESS_ITEM					= new Item(
  															SUCCESS,
  															"Whether the operation was successful",
  															SimpleType.BOOLEAN);
  
  	/**
  	 * The key ERROR, used in {@link #ERROR_ITEM}.
  	 */
  	String			ERROR							= "Error";
  
  	/**
  	 * The item containing the error message of the batch operation. The key is
  	 * {@link #ERROR} and the type is {@link SimpleType#STRING}. It is used in
  	 * {@link #BATCH_ACTION_RESULT_TYPE} and {@link #BATCH_INSTALL_RESULT_TYPE}.
  	 */
  	Item			ERROR_ITEM						= new Item(
  															ERROR,
  															"The error message if unsuccessful",
  															SimpleType.STRING);
  
  	/**
  	 * The key COMPLETED, used in {@link #COMPLETED_ITEM}.
  	 */
  	String			COMPLETED						= "Completed";
  
  	/**
  	 * The item containing the list of bundles completing the batch operation.
  	 * The key is {@link #COMPLETED} and the type is
  	 * {@link JmxConstants#LONG_ARRAY_TYPE}. It is used in
  	 * {@link #BATCH_ACTION_RESULT_TYPE} and {@link #BATCH_INSTALL_RESULT_TYPE}.
  	 */
  	Item			COMPLETED_ITEM					= new Item(
  															COMPLETED,
  															"The bundle ids of the successfully completed installs",
  															JmxConstants.LONG_ARRAY_TYPE);
  
  	/**
  	 * The key for BUNDLE_IN_ERROR. This key is used with two different items:
  	 * {@link #BUNDLE_IN_ERROR_ID_ITEM} and
  	 * {@link #BUNDLE_IN_ERROR_LOCATION_ITEM} that each have a different type
  	 * for this key. It is used in {@link #BATCH_ACTION_RESULT_TYPE} and
  	 * {@link #BATCH_INSTALL_RESULT_TYPE}.
  	 */
  	String			BUNDLE_IN_ERROR					= "BundleInError";
  
  	/**
  	 * The item containing the bundle which caused the error during the batch
  	 * operation. This item describes the bundle in error as an id. The key is
  	 * {@link #BUNDLE_IN_ERROR} and the type is {@link SimpleType#LONG}. It is
  	 * used in {@link #BATCH_ACTION_RESULT_TYPE}.
  	 *
  	 * @see #BUNDLE_IN_ERROR_LOCATION_ITEM BUNDLE_IN_ERROR_LOCATION_ITEM for the
  	 *      item that has a location for the bundle in error.
  	 */
  	Item			BUNDLE_IN_ERROR_ID_ITEM			= new Item(
  															BUNDLE_IN_ERROR,
  															"The id of the bundle causing the error",
  															SimpleType.LONG);
  
  	/**
  	 * The key REMAINING, used in {@link #REMAINING_ID_ITEM} and
  	 * {@link #REMAINING_LOCATION_ITEM}.
  	 */
  	String			REMAINING						= "Remaining";
  
  	/**
  	 * The item containing the list of remaining bundles unprocessed by the
  	 * failing batch operation. The key is {@link #REMAINING} and the type is
  	 * {@link JmxConstants#LONG_ARRAY_TYPE}. It is used in
  	 * {@link #BATCH_ACTION_RESULT_TYPE} and {@link #BATCH_INSTALL_RESULT_TYPE}.
  	 */
  	Item			REMAINING_ID_ITEM				= new Item(
  															REMAINING,
  															"The ids of the remaining bundles",
  															JmxConstants.LONG_ARRAY_TYPE);
  
  	/**
  	 * The Composite Type for a batch action result.
  	 * {@link #refreshBundle(long)} and {@link #refreshBundles(long[])}.
  	 * Notice that a batch action result returns uses an id for the
  	 * {@link #BUNDLE_IN_ERROR} while the {@link #BATCH_INSTALL_RESULT_TYPE}
  	 * uses a location.
  	 *
  	 * This Composite Type consists of the following items:
  	 * <ul>
  	 * <li>{@link #BUNDLE_IN_ERROR_ID_ITEM}</li>
  	 * <li>{@link #COMPLETED_ITEM}</li>
  	 * <li>{@link #ERROR_ITEM}</li>
  	 * <li>{@link #REMAINING_ID_ITEM}</li>
  	 * <li>{@link #SUCCESS_ITEM}</li>
  	 * </ul>
  	 */
  	CompositeType	BATCH_ACTION_RESULT_TYPE		= Item
  															.compositeType(
  																	"BUNDLE_ACTION_RESULT",
  																	"This type encapsulates a bundle batch install action result",
  																	BUNDLE_IN_ERROR_ID_ITEM,
  																	COMPLETED_ITEM,
  																	ERROR_ITEM,
  																	REMAINING_ID_ITEM,
  																	SUCCESS_ITEM
  															);
  
  	/**
  	 * The item containing the bundle which caused the error during the batch
  	 * operation. This item describes the bundle in error as a location. The key
  	 * is {@link #BUNDLE_IN_ERROR} and the type is {@link SimpleType#STRING}. It
  	 * is used in {@link #BATCH_INSTALL_RESULT_TYPE}.
  	 *
  	 * @see #BUNDLE_IN_ERROR_ID_ITEM BUNDLE_IN_ERROR_ID_ITEM for the item that
  	 *      has the id for the bundle in error.
  	 */
  	Item			BUNDLE_IN_ERROR_LOCATION_ITEM	= new Item(
  															BUNDLE_IN_ERROR,
  															"The location of the bundle causing the error",
  															SimpleType.STRING);
  
  	/**
  	 * The item containing the list of remaining bundles unprocessed by the
  	 * failing batch operation. The key is {@link #REMAINING} and the type is
  	 * {@link JmxConstants#STRING_ARRAY_TYPE}. It is used in
  	 * {@link #BATCH_ACTION_RESULT_TYPE} and {@link #BATCH_INSTALL_RESULT_TYPE}.
  	 */
  	Item			REMAINING_LOCATION_ITEM			= new Item(
  															REMAINING,
  															"The locations of the remaining bundles",
  															JmxConstants.STRING_ARRAY_TYPE);
  
  	/**
  	 * The Composite Type which represents the result of a batch install
  	 * operation. It is used in {@link #installBundles(String[])} and
  	 * {@link #installBundlesFromURL(String[], String[])}.
  	 *
  	 * This Composite Type consists of the following items:
  	 * <ul>
  	 * <li>{@link #BUNDLE_IN_ERROR_LOCATION_ITEM}</li>
  	 * <li>{@link #COMPLETED_ITEM}</li>
  	 * <li>{@link #ERROR_ITEM}</li>
  	 * <li>{@link #REMAINING_LOCATION_ITEM P }</li>
  	 * <li>{@link #SUCCESS_ITEM}</li>
  	 * </ul>
  	 */
  	CompositeType	BATCH_INSTALL_RESULT_TYPE		= Item
  															.compositeType(
  																	"BATCH_INSTALL_RESULT",
  																	"This type encapsulates a bundle batch install action result",
  																	BUNDLE_IN_ERROR_LOCATION_ITEM,
  																	COMPLETED_ITEM,
  																	ERROR_ITEM,
  																	REMAINING_LOCATION_ITEM,
  																	SUCCESS_ITEM
  															);
  
      /**
       * The Composite Type which represents the result of a batch resolve
       * operation. It is used in {@link #refreshBundlesAndWait(String[])}.
       *
       * This Composite Type consists of the following items:
       * <ul>
       * <li>{@link #COMPLETED_ITEM}</li>
       * <li>{@link #SUCCESS_ITEM}</li>
       * </ul>
       */
      CompositeType   BATCH_RESOLVE_RESULT_TYPE       = Item
                                                              .compositeType(
                                                                      "BATCH_RESOLVE_RESULT",
                                                                      "This type encapsulates a bundle batch resolve action result",
                                                                      COMPLETED_ITEM,
                                                                      SUCCESS_ITEM);
  
      /**
       * Returns the dependency closure for the specified bundles.
       *
       * <p>
       * A graph of bundles is computed starting with the specified bundles. The
       * graph is expanded by adding any bundle that is either wired to a package
       * that is currently exported by a bundle in the graph or requires a bundle
       * in the graph. The graph is fully constructed when there is no bundle
       * outside the graph that is wired to a bundle in the graph. The graph may
       * contain {@code UNINSTALLED} bundles that are
       * {@link #getRemovalPendingBundles() removal pending}.
       *
       * @param bundles The initial bundles IDs for which to generate the dependency
       *        closure.
       * @return A bundle ID array containing a snapshot of the dependency closure of
       *         the specified bundles, or an empty array if there were no
       *         specified bundles.
       * @throws IOException if the operation failed
       */
      long[] getDependencyClosure(long[] bundles) throws IOException;
  
      /**
  	 * Retrieve the framework start level
  	 *
  	 * @return the framework start level
  	 * @throws IOException if the operation failed
  	 */
  	int getFrameworkStartLevel() throws IOException;
  
  	/**
  	 * Answer the initial start level assigned to a bundle when it is first
  	 * started
  	 *
  	 * @return the start level
  	 * @throws IOException if the operation failed
  	 */
  	int getInitialBundleStartLevel() throws IOException;
  
      /**
       * Returns the value of the specified property. If the key is not found in
       * the Framework properties, the system properties are then searched. The
       * method returns {@code null} if the property is not found.
       *
       * @param key The name of the requested property.
       * @return The value of the requested property, or {@code null} if the
       *         property is undefined.
       * @throws IOException if the operation failed
       */
      String getProperty(String key) throws IOException;
  
  	/**
       * Returns the bundles IDs that have non-current, in use bundle wirings. This
       * is typically the bundles which have been updated or uninstalled since the
       * last call to {@link #refreshBundles(long[])}.
       *
       * @return A bundle ID array containing a snapshot of the bundles which
       *         have non-current, in use bundle wirings, or an empty
       *         array if there are no such bundles.
       * @throws IOException if the operation failed
       */
      long[] getRemovalPendingBundles() throws IOException;
  
  	/**
  	 * Install the bundle indicated by the bundleLocations
  	 *
  	 * @param location the location of the bundle to install
  	 * @return the bundle id the installed bundle
  	 * @throws IOException if the operation does not succeed
  	 */
  	long installBundle(String location) throws IOException;
  
  	/**
  	 * Install the bundle indicated by the bundleLocations
  	 *
  	 * @param location the location to assign to the bundle
  	 * @param url the URL which will supply the bytes for the bundle
  	 * @return the bundle id the installed bundle
  	 * @throws IOException if the operation does not succeed
  	 */
  	long installBundleFromURL(String location, String url) throws IOException;
  
  	/**
  	 * Batch install the bundles indicated by the list of bundleLocationUrls
  	 *
  	 * @see #BATCH_INSTALL_RESULT_TYPE BATCH_INSTALL_RESULT_TYPE for the precise
  	 *      specification of the CompositeData type representing the returned
  	 *      result.
  	 *
  	 * @param locations the array of locations of the bundles to install
  	 * @return the resulting state from executing the operation
  	 * @throws IOException if the operation does not succeed
  	 */
  	CompositeData installBundles(String[] locations) throws IOException;
  
  	/**
  	 * Batch install the bundles indicated by the list of bundleLocationUrls
  	 *
  	 * @see #BATCH_INSTALL_RESULT_TYPE BATCH_INSTALL_RESULT_TYPE
  	 *      BatchBundleResult for the precise specification of the CompositeData
  	 *      type representing the returned result.
  	 *
  	 * @param locations the array of locations to assign to the installed
  	 *        bundles
  	 * @param urls the array of urls which supply the bundle bytes
  	 * @return the resulting state from executing the operation
  	 * @throws IOException if the operation does not succeed
  	 */
  	CompositeData installBundlesFromURL(String[] locations, String[] urls)
  			throws IOException;
  
  	/**
  	 * Force the update, replacement or removal of the packages identified by
  	 * the specified bundle.
  	 *
  	 * @param bundleIdentifier the bundle identifier
  	 * @throws IOException if the operation failed
  	 */
  	void refreshBundle(long bundleIdentifier) throws IOException;
  	boolean refreshBundleAndWait(long bundleIdentifier) throws IOException;
  
  	/**
  	 * Force the update, replacement or removal of the packages identified by
  	 * the list of bundles.
  	 *
  	 * @param bundleIdentifiers The identifiers of the bundles to refresh, or
  	 *        <code>null</code> for all bundles with packages pending removal.
  	 * @throws IOException if the operation failed
  	 */
  	void refreshBundles(long[] bundleIdentifiers) throws IOException;
  	CompositeData refreshBundlesAndWait(long[] bundleIdentifiers) throws IOException;
  
  	/**
  	 * Resolve the bundle indicated by the unique symbolic name and version
  	 *
  	 * @param bundleIdentifier the bundle identifier
  	 * @return <code>true</code> if the bundle was resolved, false otherwise
  	 * @throws IOException if the operation does not succeed
  	 * @throws IllegalArgumentException if the bundle indicated does not exist
  	 */
  	boolean resolveBundle(long bundleIdentifier) throws IOException;
  
  	/**
  	 * Batch resolve the bundles indicated by the list of bundle identifiers
  	 *
  	 * @param bundleIdentifiers The identifiers of the bundles to resolve, or
  	 *        <code>null</code> to resolve all unresolved bundles.
  	 * @return <code>true</code> if the bundles were resolved, false otherwise
  	 * @throws IOException if the operation does not succeed
  	 */
  	boolean resolveBundles(long[] bundleIdentifiers) throws IOException;
  
  	/**
  	 * Same as {@link #resolveBundles(long[])} but with a more detailed return type.
  	 * @param bundleIdentifiers
  	 * @return
  	 * @throws IOException
  	 */
  	CompositeData resolve(long[] bundleIdentifiers) throws IOException;
  
  	/**
  	 * Restart the framework by updating the system bundle
  	 *
  	 * @throws IOException if the operation failed
  	 */
  	void restartFramework() throws IOException;
  
  	/**
  	 * Set the start level for the bundle identifier
  	 *
  	 * @param bundleIdentifier the bundle identifier
  	 * @param newlevel the new start level for the bundle
  	 * @throws IOException if the operation failed
  	 */
  	void setBundleStartLevel(long bundleIdentifier, int newlevel)
  			throws IOException;
  
  	/**
  	 * Set the start levels for the list of bundles.
  	 *
  	 * @see #BATCH_ACTION_RESULT_TYPE BATCH_ACTION_RESULT_TYPE for the precise
  	 *      specification of the CompositeData type representing the returned
  	 *      result.
  	 *
  	 * @param bundleIdentifiers the array of bundle identifiers
  	 * @param newlevels the array of new start level for the bundles
  	 * @return the resulting state from executing the operation
  	 * @throws IOException if the operation failed
  	 */
  	CompositeData setBundleStartLevels(long[] bundleIdentifiers, int[] newlevels)
  			throws IOException;
  
  	/**
  	 * Set the start level for the framework
  	 *
  	 * @param newlevel the new start level
  	 * @throws IOException if the operation failed
  	 */
  	void setFrameworkStartLevel(int newlevel) throws IOException;
  
  	/**
  	 * Set the initial start level assigned to a bundle when it is first started
  	 *
  	 * @param newlevel the new start level
  	 * @throws IOException if the operation failed
  	 */
  	void setInitialBundleStartLevel(int newlevel) throws IOException;
  
  	/**
  	 * Shutdown the framework by stopping the system bundle
  	 *
  	 * @throws IOException if the operation failed
  	 */
  	void shutdownFramework() throws IOException;
  
  	/**
  	 * Start the bundle indicated by the bundle identifier
  	 *
  	 * @param bundleIdentifier the bundle identifier
  	 * @throws IOException if the operation does not succeed
  	 * @throws IllegalArgumentException if the bundle indicated does not exist
  	 */
  	void startBundle(long bundleIdentifier) throws IOException;
  
  	/**
  	 * Batch start the bundles indicated by the list of bundle identifier
  	 *
  	 * @see #BATCH_ACTION_RESULT_TYPE BATCH_ACTION_RESULT_TYPE for the precise
  	 *      specification of the CompositeData type representing the returned
  	 *      result.
  	 *
  	 * @param bundleIdentifiers the array of bundle identifiers
  	 * @return the resulting state from executing the operation
  	 * @throws IOException if the operation does not succeed
  	 */
  	CompositeData startBundles(long[] bundleIdentifiers) throws IOException;
  
  	/**
  	 * Stop the bundle indicated by the bundle identifier
  	 *
  	 * @param bundleIdentifier the bundle identifier
  	 * @throws IOException if the operation does not succeed
  	 * @throws IllegalArgumentException if the bundle indicated does not exist
  	 */
  	void stopBundle(long bundleIdentifier) throws IOException;
  
  	/**
  	 * Batch stop the bundles indicated by the list of bundle identifier
  	 *
  	 * @see #BATCH_ACTION_RESULT_TYPE BATCH_ACTION_RESULT_TYPE for the precise
  	 *      specification of the CompositeData type representing the returned
  	 *      result.
  	 *
  	 * @param bundleIdentifiers the array of bundle identifiers
  	 * @return the resulting state from executing the operation
  	 * @throws IOException if the operation does not succeed
  	 */
  	CompositeData stopBundles(long[] bundleIdentifiers) throws IOException;
  
  	/**
  	 * Uninstall the bundle indicated by the bundle identifier
  	 *
  	 * @param bundleIdentifier the bundle identifier
  	 * @throws IOException if the operation does not succeed
  	 * @throws IllegalArgumentException if the bundle indicated does not exist
  	 */
  	void uninstallBundle(long bundleIdentifier) throws IOException;
  
  	/**
  	 * Batch uninstall the bundles indicated by the list of bundle identifiers
  	 *
  	 * @see #BATCH_ACTION_RESULT_TYPE BATCH_ACTION_RESULT_TYPE for the precise
  	 *      specification of the CompositeData type representing the returned
  	 *      result.
  	 *
  	 * @param bundleIdentifiers the array of bundle identifiers
  	 * @return the resulting state from executing the operation
  	 * @throws IOException if the operation does not succeed
  	 */
  	CompositeData uninstallBundles(long[] bundleIdentifiers) throws IOException;
  
  	/**
  	 * Update the bundle indicated by the bundle identifier
  	 *
  	 * @param bundleIdentifier the bundle identifier
  	 * @throws IOException if the operation does not succeed
  	 * @throws IllegalArgumentException if the bundle indicated does not exist
  	 */
  	void updateBundle(long bundleIdentifier) throws IOException;
  
  	/**
  	 * Update the bundle identified by the bundle identifier
  	 *
  	 * @param bundleIdentifier the bundle identifier
  	 * @param url the URL to use to update the bundle
  	 * @throws IOException if the operation does not succeed
  	 * @throws IllegalArgumentException if the bundle indicated does not exist
  	 */
  	void updateBundleFromURL(long bundleIdentifier, String url) throws IOException;
  
  	/**
  	 * Batch update the bundles indicated by the list of bundle identifier.
  	 *
  	 * @see #BATCH_ACTION_RESULT_TYPE BATCH_ACTION_RESULT_TYPE for the precise
  	 *      specification of the CompositeData type representing the returned
  	 *      result.
  	 *
  	 * @param bundleIdentifiers the array of bundle identifiers
  	 * @return the resulting state from executing the operation
  	 * @throws IOException if the operation does not succeed
  	 */
  	CompositeData updateBundles(long[] bundleIdentifiers) throws IOException;
  
  	/**
  	 * Update the bundle uniquely identified by the bundle symbolic name and
  	 * version using the contents of the supplied urls.
  	 *
  	 * @see #BATCH_ACTION_RESULT_TYPE BATCH_ACTION_RESULT_TYPE for the precise
  	 *      specification of the CompositeData type representing the returned
  	 *      result.
  	 *
  	 * @param bundleIdentifiers the array of bundle identifiers
  	 * @param urls the array of URLs to use to update the bundles
  	 * @return the resulting state from executing the operation
  	 * @throws IOException if the operation does not succeed
  	 * @throws IllegalArgumentException if the bundle indicated does not exist
  	 */
  	CompositeData updateBundlesFromURL(long[] bundleIdentifiers, String[] urls)
  			throws IOException;
  
  	/**
  	 * Update the framework by updating the system bundle.
  	 *
  	 * @throws IOException if the operation failed
  	 */
  	void updateFramework() throws IOException;
  
   }