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 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$
   * @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:
  	 * <ul>
  	 * <li>{@link #BUNDLE_IDENTIFIER}</li>
  	 * <li>{@link #IDENTIFIER}</li>
  	 * <li>{@link #OBJECT_CLASS}</li>
  	 * <li>{@link #USING_BUNDLES}</li>
  	 * </ul>
  	 */
  	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:
  	 * <ul>
  	 * <li>{@link #IDENTIFIER}</li>
  	 * <li>{@link #OBJECT_CLASS}</li>
  	 * <li>{@link #BUNDLE_LOCATION}</li>
  	 * <li>{@link #BUNDLE_SYMBOLIC_NAME}</li>
  	 * <li>{@link #EVENT}</li>
  	 * </ul>
  	 */
  	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
  	 *         <code>org.osgi.framework.Constants</code> 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;
  
  }
  