jmx/jmx-blueprint-api/src/main/java/org/apache/aries/jmx/blueprint/BlueprintStateMBean.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.apache.aries.jmx.blueprint;

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;

/**
 * This MBean provides the management interface to the OSGi Blueprint Service.
 *
 * This MBean also emits events that clients can use to get notified of the
 * changes in the blueprint containers state in the framework.
 *
 * @version $Revision$
 */
public interface BlueprintStateMBean {
    /**
     * The object name for this MBean.
     */
    String OBJECTNAME = JmxConstants.ARIES_BLUEPRINT+":service=blueprintState,version=1.0";

    ///////////////////////////////////////////////////////////////
    // Define Event's CompositeType
    ///////////////////////////////////////////////////////////////

    /**
     * The key BUNDLE_ID, used in {@link #BUNDLE_ID_ITEM}.
     */
    String          BUNDLE_ID                  = "BundleId";

    /**
     * The item containing the Blueprint bundle id associated with this event.
     * The key is {@link #BUNDLE_ID}, and the type is {@link SimpleType#LONG}.
     */
    Item            BUNDLE_ID_ITEM             = new Item(
                                                    BUNDLE_ID,
                                                    "the Blueprint bundle id associated with this event.",
                                                    SimpleType.LONG);

    /**
     * The key EXTENDER_BUNDLE_ID, used in {@link #EXTENDER_BUNDLE_ID_ITEM}.
     */
    String          EXTENDER_BUNDLE_ID   = "ExtenderBundleId";

    /**
     * The item containing the Blueprint extender bundle id that is generating this event.
     * The key is {@link #EXTENDER_BUNDLE_ID}, and the type is {@link SimpleType#LONG}.
     */
    Item            EXTENDER_BUNDLE_ID_ITEM    = new Item(
                                                    EXTENDER_BUNDLE_ID,
                                                    "the Blueprint extender bundle id that is generating this event.",
                                                    SimpleType.LONG);

    /**
     * The key REPLAY, used in {@link #REPLAY_ITEM}.
     */
    String          REPLAY               = "Replay";

    /**
     * The item containing the flag that represents whether this event is a replay event.
     * The key is {@link #REPLAY}, and the type is {@link SimpleType#BOOLEAN}.
     */
    Item            REPLAY_ITEM          = new Item(
                                                    REPLAY,
                                                    "the flag that represents whether this event is a replay event.",
                                                    SimpleType.BOOLEAN);


    /**
     * The key EVENT_TYPE, used in {@link #EVENT_TYPE_ITEM}.
     */
    String          EVENT_TYPE                    = "EventType";

    /**
     * The item containing the type of this event.
     * The key is {@link #EVENT_TYPE}, and the type is {@link SimpleType#STRING}.
     */
    Item            EVENT_TYPE_ITEM              = new Item(
                                                    EVENT_TYPE,
                                                    "The type of the event: {CREATING=1, CREATED=2, DESTROYING=3, DESTROYED=4, FAILURE=5, GRACE_PERIOD=6, WAITING=7}",
                                                    SimpleType.INTEGER);

    /**
     * The key TIMESTAMP, used in {@link #TIMESTAMP_ITEM}.
     */
    String          TIMESTAMP               = "Timestamp";

    /**
     * The item containing the time at which this event was created.
     * The key is {@link #TIMESTAMP}, and the type is {@link SimpleType#LONG}.
     */
    Item            TIMESTAMP_ITEM          = new Item(
                                                    TIMESTAMP,
                                                    "the time at which this event was created.",
                                                    SimpleType.LONG);


    /**
     * The key DEPENDENCIES, used in {@link #DEPENDENCIES_ITEM}.
     */
    String          DEPENDENCIES            = "Dependencies";

    /**
     * The item containing the filters identifying the missing dependencies that caused the WAITING, GRACE_PERIOD or FAILURE event.
     * The key is {@link #DEPENDENCIES}, and the type is {@link JmxConstants#STRING_ARRAY_TYPE}.
     */
    Item            DEPENDENCIES_ITEM       = new Item(
                                                    DEPENDENCIES,
                                                    "the filters identifying the missing dependencies that caused the WAITING, GRACE_PERIOD or FAILURE event.",
                                                    JmxConstants.STRING_ARRAY_TYPE);

    /**
     * The key EXCEPTION_MESSAGE, used in {@link #EXCEPTION_MESSAGE_ITEM}.
     */
    String          EXCEPTION_MESSAGE       = "ExceptionMessage";

    /**
     * The item containing the exception message that cause this FAILURE event.
     * The key is {@link #EXCEPTION_MESSAGE}, and the type is {@link SimpleType#STRING}.
     */
    Item            EXCEPTION_MESSAGE_ITEM  = new Item(
                                                    EXCEPTION_MESSAGE,
                                                    "the exception message that cause this FAILURE event.",
                                                    SimpleType.STRING);

    /**
     * The CompositeType for a blueprint event. It contains the following items:
     * <ul>
     * <li>{@link #BUNDLE_ID}</li>
     * <li>{@link #EXTENDER_BUNDLE_ID}</li>
     * <li>{@link #EVENT_TYPE}</li>
     * <li>{@link #REPLAY}</li>
     * <li>{@link #TIMESTAMP}</li>
     * <li>{@link #DEPENDENCIES}</li>
     * <li>{@link #EXCEPTION_MESSAGE}</li>
     * </ul>
     */
    CompositeType   OSGI_BLUEPRINT_EVENT_TYPE   = Item.compositeType(
                                                    "OSGI_BLUEPRINT_EVENT",
                                                    "Blueprint event",
                                                    BUNDLE_ID_ITEM,
                                                    EXTENDER_BUNDLE_ID_ITEM,
                                                    EVENT_TYPE_ITEM,
                                                    REPLAY_ITEM,
                                                    TIMESTAMP_ITEM,
                                                    DEPENDENCIES_ITEM,
                                                    EXCEPTION_MESSAGE_ITEM);


    /**
     * The Tabular Type for A list of blueprint events. The row type is
     * {@link #OSGI_BLUEPRINT_EVENT_TYPE}.
     */
    TabularType     OSGI_BLUEPRINT_EVENTS_TYPE  = Item.tabularType(
                                                    "BUNDLES",
                                                    "A list of blueprint events",
                                                    OSGI_BLUEPRINT_EVENT_TYPE,
                                                    new String[] { BUNDLE_ID });

    /**
     * Returns the BlueprintEvent associated with this blueprint container.
     * The returned Composite Data is typed by {@link #OSGI_BLUEPRINT_EVENT_TYPE}.
     *
     * @param bundleId The bundle id of a blueprint bundle
     * @return the last event associated with the blueprint bundle, see {@link #OSGI_BLUEPRINT_EVENT_TYPE}
     * @throws IOException if the operation fails
     * @throws IllegalArgumentException if the bundle is not a blueprint bundle
     */
    public CompositeData getLastEvent(long bundleId) throws IOException;

    /**
     * Returns all the last events associated with the blueprint bundles.
     *
     * @return the tabular representation of all the last events associated with the blueprint bundles see {@link #OSGI_BLUEPRINT_EVENTS_TYPE}
     * @throws IOException if the operation fails
     */
    public TabularData getLastEvents() throws IOException;

    /**
     * Returns all the blueprint bundles' IDs, which are either
     * successfully created or not by current extender.
     *
     * @return the list of all the blueprint bundles's IDs (either successfully created or not by current extender)
     * @throws IOException if the operation fails
     */
    public long[] getBlueprintBundleIds() throws IOException;

}