org.osgi.jmx.framework.ServiceStateMBean Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of org.apache.aries.jmx.api Show documentation
This bundle contains the JMX 1.1.0 API
The newest version!
/*
 * 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 javax.management.openmbean.TabularData;
import javax.management.openmbean.TabularType;

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

/**
 * This MBean represents the Service state of the framework. This MBean also
 * emits events that clients can use to get notified of the changes in the
 * service state of the framework.
 *
 * @version $Revision: 1226784 $
 * @ThreadSafe
 */
public interface ServiceStateMBean {
	/**
	 * The fully qualified object name of this mbean.
	 */
	String OBJECTNAME = JmxConstants.OSGI_CORE
			+ ":type=serviceState,version=1.7";
	/**
	 * The key BUNDLE_IDENTIFIER, used in {@link #BUNDLE_IDENTIFIER_ITEM}.
	 */
	String BUNDLE_IDENTIFIER = "BundleIdentifier";
	/**
	 * The item containing the bundle identifier in {@link #SERVICE_TYPE}. The
	 * key is {@link #BUNDLE_IDENTIFIER} and the type is {@link SimpleType#LONG}
	 * .
	 */
	Item BUNDLE_IDENTIFIER_ITEM = new Item(BUNDLE_IDENTIFIER,
			"The identifier of the bundle the service belongs to",
			SimpleType.LONG);

	/**
	 * The key OBJECT_CLASS, used {@link #OBJECT_CLASS_ITEM}.
	 */
	String OBJECT_CLASS = "objectClass";

	/**
	 * The item containing the interfaces of the service in
	 * {@link #SERVICE_TYPE}. The key is {@link #OBJECT_CLASS} and the type is
	 * {@link JmxConstants#STRING_ARRAY_TYPE}.
	 */
	Item OBJECT_CLASS_ITEM = new Item(
			OBJECT_CLASS,
			"An string array containing the interfaces under which the service has been registered",
			JmxConstants.STRING_ARRAY_TYPE);

	/**
	 * The key IDENTIFIER, used {@link #IDENTIFIER_ITEM}.
	 */
	String IDENTIFIER = "Identifier";

	/**
	 * The item containing the service identifier in {@link #SERVICE_TYPE}. The
	 * key is {@link #IDENTIFIER} and the type is {@link SimpleType#LONG}.
	 */
	Item IDENTIFIER_ITEM = new Item(IDENTIFIER,
			"The identifier of the service", SimpleType.LONG);

	/**
	 * The key PROPERTIES, used in {@link #PROPERTIES_ITEM}.
	 */
	String PROPERTIES = "Properties";

	/**
	 * The item containing service properties in {@link #SERVICE_TYPE}. The key
	 * is {@link #PROPERTIES} and the type is {@link JmxConstants#PROPERTIES_TYPE}.
	 */
	Item PROPERTIES_ITEM = new Item(PROPERTIES,
	        "The service properties", JmxConstants.PROPERTIES_TYPE);

	/**
	 * The key USING_BUNDLES, used in {@link #USING_BUNDLES_ITEM}.
	 */
	String USING_BUNDLES = "UsingBundles";

	/**
	 * The item containing the bundles using the service in
	 * {@link #SERVICE_TYPE}. The key is {@link #USING_BUNDLES} and the type is
	 * {@link JmxConstants#LONG_ARRAY_TYPE}.
	 */
	Item USING_BUNDLES_ITEM = new Item(USING_BUNDLES,
			"The bundles using the service", JmxConstants.LONG_ARRAY_TYPE);

	/**
	 * The Composite Type for a CompositeData representing a service. This type
	 * consists of:
	 * 
	 * {@link #BUNDLE_IDENTIFIER}
	 * {@link #IDENTIFIER}
	 * {@link #OBJECT_CLASS}
	 * {@link #USING_BUNDLES}
	 * 
	 */
	CompositeType SERVICE_TYPE = Item.compositeType("SERVICE",
			"This type encapsulates an OSGi service", BUNDLE_IDENTIFIER_ITEM,
			IDENTIFIER_ITEM, OBJECT_CLASS_ITEM, PROPERTIES_ITEM,
			USING_BUNDLES_ITEM);

	/**
	 * The Tabular Type for a Service table. The rows consists of
	 * {@link #SERVICE_TYPE} Composite Data and the index is {@link #IDENTIFIER}
	 * .
	 */
	TabularType SERVICES_TYPE = Item.tabularType("SERVICES",
			"The table of all services", SERVICE_TYPE, IDENTIFIER);

	/**
	 * The key BUNDLE_LOCATION, used in {@link #SERVICE_EVENT_TYPE}.
	 */
	String BUNDLE_LOCATION = "BundleLocation";
	/**
	 * The item containing the bundle location in {@link #EVENT_ITEM}. The key
	 * is {@link #BUNDLE_LOCATION} and the the type is {@link SimpleType#STRING}
	 * .
	 */
	Item BUNDLE_LOCATION_ITEM = new Item(BUNDLE_LOCATION,
			"The location of the bundle", SimpleType.STRING);
	/**
	 * The key BUNDLE_SYMBOLIC_NAME, used in {@link #SERVICE_EVENT_TYPE}.
	 */
	String BUNDLE_SYMBOLIC_NAME = "BundleSymbolicName";

	/**
	 * The item containing the symbolic name in {@link #EVENT}. The key is
	 * {@link #BUNDLE_SYMBOLIC_NAME} and the the type is
	 * {@link SimpleType#STRING}.
	 */
	Item BUNDLE_SYMBOLIC_NAME_ITEM = new Item(BUNDLE_SYMBOLIC_NAME,
			"The symbolic name of the bundle", SimpleType.STRING);

	/**
	 * The key EVENT, used in {@link #EVENT_ITEM}.
	 */
	String EVENT = "ServiceEvent";

	/**
	 * The item containing the event type. The key is {@link #EVENT} and the
	 * type is {@link SimpleType#INTEGER}
	 */
	Item EVENT_ITEM = new Item(
			EVENT,
			"The eventType of the event: {REGISTERED=1, MODIFIED=2 UNREGISTERING=3}",
			SimpleType.INTEGER);

	/**
	 * The Composite Type that represents a service event. This composite
	 * consists of:
	 * 
	 * {@link #IDENTIFIER}
	 * {@link #OBJECT_CLASS}
	 * {@link #BUNDLE_LOCATION}
	 * {@link #BUNDLE_SYMBOLIC_NAME}
	 * {@link #EVENT}
	 * 
	 */
	CompositeType SERVICE_EVENT_TYPE = Item.compositeType("SERVICE_EVENT",
			"This type encapsulates OSGi service events", IDENTIFIER_ITEM,
			OBJECT_CLASS_ITEM, BUNDLE_IDENTIFIER_ITEM, BUNDLE_LOCATION_ITEM,
			BUNDLE_SYMBOLIC_NAME_ITEM, EVENT_ITEM);

	/**
	 * Answer the list of interfaces that this service implements
	 *
	 * @param serviceId
	 *            the identifier of the service
	 * @return the list of interfaces
	 * @throws IOException
	 *             if the operation fails
	 * @throws IllegalArgumentException
	 *             if the service indicated does not exist
	 */
	public String[] getObjectClass(long serviceId) throws IOException;

	/**
	 * Answer the bundle identifier of the bundle which registered the service
	 *
	 * @param serviceId
	 *            the identifier of the service
	 * @return the identifier for the bundle
	 * @throws IOException
	 *             if the operation fails
	 * @throws IllegalArgumentException
	 *             if the service indicated does not exist
	 */
	long getBundleIdentifier(long serviceId) throws IOException;
	CompositeData getService(long serviceId) throws IOException;

	/**
	 * Answer the map of properties associated with this service
	 *
	 * @see JmxConstants#PROPERTIES_TYPE for the details of the TabularType
	 *
	 * @param serviceId
	 *            the identifier of the service
	 * @return the table of properties. These include the standard mandatory
	 *         service.id and objectClass properties as defined in the
	 *         org.osgi.framework.Constants interface
	 * @throws IOException
	 *             if the operation fails
	 * @throws IllegalArgumentException
	 *             if the service indicated does not exist
	 */
	TabularData getProperties(long serviceId) throws IOException;
	CompositeData getProperty(long serviceId, String key) throws IOException;
	long[] getServiceIds() throws IOException;

	/**
	 * Answer the service state of the system in tabular form.
	 *
	 * @see #SERVICES_TYPE for the details of the TabularType
	 *
	 * @return the tabular representation of the service state
	 * @throws IOException
	 *             If the operation fails
	 * @throws IllegalArgumentException
	 *             if the service indicated does not exist
	 */
	TabularData listServices() throws IOException;
	TabularData listServices(String clazz, String filter) throws IOException;
    TabularData listServices(String clazz, String filter, String ... serviceTypeItems) throws IOException;

	/**
	 * Answer the list of identifiers of the bundles that use the service
	 *
	 * @param serviceId
	 *            the identifier of the service
	 * @return the list of bundle identifiers
	 * @throws IOException
	 *             if the operation fails
	 * @throws IllegalArgumentException
	 *             if the service indicated does not exist
	 */
	long[] getUsingBundles(long serviceId) throws IOException;

}