PackageStateMBean.java

/*
 * 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.CompositeType;
import javax.management.openmbean.SimpleType;
import javax.management.openmbean.TabularData;
import javax.management.openmbean.TabularType;

import org.osgi.jmx.Item;
import org.osgi.jmx.JmxConstants;

/**
 * This MBean provides information about the package state of the framework.
 * 
 * @version $Revision$
 * @ThreadSafe
 */
public interface PackageStateMBean {
	/**
	 * The fully qualified object name of this MBean.
	 */
	String			OBJECTNAME				= JmxConstants.OSGI_CORE
													+ ":type=packageState,version=1.5";

	/**
	 * The key EXPORTING_BUNDLE, used in {@link #EXPORTING_BUNDLES_ITEM}.
	 */
	String			EXPORTING_BUNDLES		= "ExportingBundles";

	/**
	 * The item containing the bundle identifier in {@link #PACKAGE_TYPE}. The
	 * key is {@link #EXPORTING_BUNDLES} and the type is
	 * {@link JmxConstants#LONG_ARRAY_TYPE}.
	 */
	Item			EXPORTING_BUNDLES_ITEM	= new Item(
													EXPORTING_BUNDLES,
													"The bundles the package belongs to",
													JmxConstants.LONG_ARRAY_TYPE);

	/**
	 * The key IMPORTING_BUNDLES, used in {@link #IMPORTING_BUNDLES_ITEM}.
	 */
	String			IMPORTING_BUNDLES		= "ImportingBundles";

	/**
	 * The item containing the bundle identifier in {@link #PACKAGE_TYPE}. The
	 * key is {@link #IMPORTING_BUNDLES} and the type is {@link JmxConstants#LONG_ARRAY_TYPE}.
	 */
	Item			IMPORTING_BUNDLES_ITEM	= new Item(
													IMPORTING_BUNDLES,
													"The importing bundles of the package",
													JmxConstants.LONG_ARRAY_TYPE);


	/**
	 * The key NAME, used in {@link #NAME_ITEM}.
	 */
	String			NAME					= "Name";

	/**
	 * The item containing the name of the package in {@link #PACKAGE_TYPE}.
	 * The key is {@link #NAME} and the type is {@link SimpleType#LONG}.
	 */
	Item			NAME_ITEM				= new Item(NAME,
													"The package name",
													SimpleType.STRING);

	/**
	 * The name of the item containing the pending removal status of the package
	 * in the CompositeData. Used
	 */
	String			REMOVAL_PENDING			= "RemovalPending";
	/**
	 * The item representing the removal pending status of a package. The key is
	 * {@link #REMOVAL_PENDING} and the type is {@link SimpleType#BOOLEAN}.
	 */
	Item			REMOVAL_PENDING_ITEM	= new Item(
													REMOVAL_PENDING,
													"Whether the package is pending removal",
													SimpleType.BOOLEAN);

	/**
	 * The name of the item containing the package version in the CompositeData.
	 * Used in {@link #VERSION_ITEM}.
	 */
	String			VERSION					= "Version";

	/**
	 * The item containing the version of the package in {@link #PACKAGE_TYPE}.
	 * The key is {@link #VERSION} and the type is {@link SimpleType#STRING}.
	 */
	Item			VERSION_ITEM			= new Item(
													VERSION,
													"The identifier of the bundle the service belongs to",
													SimpleType.STRING);

	/**
	 * The Composite Type for a CompositeData representing a package. This type
	 * consists of:
	 * <ul>
	 * <li>{@link #EXPORTING_BUNDLES_ITEM}</li>
	 * <li>{@link #IMPORTING_BUNDLES_ITEM}</li>
	 * <li>{@link #NAME_ITEM}</li>
	 * <li>{@link #REMOVAL_PENDING_ITEM}</li>
	 * <li>{@link #VERSION_ITEM}</li>
	 * </ul>
	 * The key is defined as {@link #NAME} and {@link #EXPORTING_BUNDLES}
	 */
	CompositeType	PACKAGE_TYPE			= Item
													.compositeType(
															"PACKAGE",
															"This type encapsulates an OSGi package",
															EXPORTING_BUNDLES_ITEM,
															IMPORTING_BUNDLES_ITEM,
															NAME_ITEM,
															REMOVAL_PENDING_ITEM,
															VERSION_ITEM);

	/**
	 * The Tabular Type used in {@link #listPackages()}. They key is
	 * {@link #NAME}, {@link #VERSION}, and {@link #EXPORTING_BUNDLES}.
	 */
	TabularType		PACKAGES_TYPE			= Item.tabularType("PACKAGES",
													"A table of packages",
													PACKAGE_TYPE, NAME,
													VERSION, EXPORTING_BUNDLES);

	/**
	 * Answer the identifier of the bundle exporting the package
	 * 
	 * @param packageName - the package name
	 * @param version - the version of the package
	 * @return the bundle identifiers exporting such a package
	 * @throws IOException if the operation fails
	 * @throws IllegalArgumentException if the package indicated does not exist
	 */
	long[] getExportingBundles(String packageName, String version)
			throws IOException;

	/**
	 * Answer the list of identifiers of the bundles importing the package
	 * 
	 * @param packageName The package name
	 * @param version The version of the package
	 * @param exportingBundle The exporting bundle for the given package
	 * @return the list of bundle identifiers
	 * @throws IOException if the operation fails
	 * @throws IllegalArgumentException if the package indicated does not exist
	 * 
	 */
	long[] getImportingBundles(String packageName, String version,
			long exportingBundle) throws IOException;

	/**
	 * Answer the package state of the system in tabular form
	 * 
	 * The Tabular Data is typed by {@link #PACKAGES_TYPE}, which has
	 * {@link #PACKAGE_TYPE} as its Composite Type.
	 * 
	 * @return the tabular representation of the package state
	 * @throws IOException When fails
	 */
	TabularData listPackages() throws IOException;

	/**
	 * Answer if this package is exported by a bundle which has been updated or
	 * uninstalled
	 * 
	 * @param packageName The package name
	 * @param version The version of the package
	 * @param exportingBundle The bundle exporting the package
	 * @return true if this package is being exported by a bundle that has been
	 *         updated or uninstalled.
	 * @throws IOException if the operation fails
	 * @throws IllegalArgumentException if the package indicated does not exist
	 */
	boolean isRemovalPending(String packageName, String version, long exportingBundle)
			throws IOException;

}