1. /*

  2.  * ====================================================================

  3.  *

  4.  * The Apache Software License, Version 1.1

  5.  *

  6.  * Copyright (c) 2001-2003 The Apache Software Foundation.  All rights

  7.  * reserved.

  8.  *

  9.  * Redistribution and use in source and binary forms, with or without

  10.  * modification, are permitted provided that the following conditions

  11.  * are met:

  12.  *

  13.  * 1. Redistributions of source code must retain the above copyright

  14.  *    notice, this list of conditions and the following disclaimer.

  15.  *

  16.  * 2. Redistributions in binary form must reproduce the above copyright

  17.  *    notice, this list of conditions and the following disclaimer in

  18.  *    the documentation and/or other materials provided with the

  19.  *    distribution.

  20.  *

  21.  * 3. The end-user documentation included with the redistribution, if

  22.  *    any, must include the following acknowlegement:

  23.  *       "This product includes software developed by the

  24.  *        Apache Software Foundation (http://www.apache.org/)."

  25.  *    Alternately, this acknowlegement may appear in the software itself,

  26.  *    if and wherever such third-party acknowlegements normally appear.

  27.  *

  28.  * 4. The names "The Jakarta Project", "Commons", and "Apache Software

  29.  *    Foundation" must not be used to endorse or promote products derived

  30.  *    from this software without prior written permission. For written

  31.  *    permission, please contact apache@apache.org.

  32.  *

  33.  * 5. Products derived from this software may not be called "Apache"

  34.  *    nor may "Apache" appear in their names without prior written

  35.  *    permission of the Apache Group.

  36.  *

  37.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED

  38.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

  39.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

  40.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR

  41.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

  42.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

  43.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF

  44.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

  45.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

  46.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT

  47.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

  48.  * SUCH DAMAGE.

  49.  * ====================================================================

  50.  *

  51.  * This software consists of voluntary contributions made by many

  52.  * individuals on behalf of the Apache Software Foundation.  For more

  53.  * information on the Apache Software Foundation, please see

  54.  * <http://www.apache.org/>.

  55.  *

  56.  * [Additional notices, if required by prior licensing conditions]

  57.  *

  58.  */

  59. 

  60. 

  61. package org.apache.commons.modeler;

  62. 

  63. 

  64. import java.util.List;

  65. 

  66. /**

  67.  * Interface for modeler MBeans.

  68.  * 

  69.  * This is the main entry point into modeler. It provides methods to create

  70.  * and manipulate model mbeans and simplify their use.

  71.  *

  72.  * Starting with version 1.1, this is no longer a singleton and the static

  73.  * methods are strongly deprecated. In a container environment we can expect

  74.  * different applications to use different registries.

  75.  * 

  76.  * @author Craig R. McClanahan

  77.  * @author Costin Manolache

  78.  * 

  79.  * @since 1.1

  80.  */

  81. public interface RegistryMBean {

  82. 

  83.     /** 

  84.      * Load an extended mlet file. The source can be an URL, File or

  85.      * InputStream. 

  86.      * 

  87.      * All mbeans will be instantiated, registered and the attributes will be 

  88.      * set. The result is a list of ObjectNames.

  89.      *

  90.      * @param source InputStream or URL of the file

  91.      * @param cl ClassLoader to be used to load the mbeans, or null to use the

  92.      *        default JMX mechanism ( i.e. all registered loaders )

  93.      * @return List of ObjectName for the loaded mbeans

  94.      * @throws Exception

  95.      * 

  96.      * @since 1.1

  97.      */ 

  98.     public List loadMBeans( Object source, ClassLoader cl ) throws Exception;

  99. 

  100.     /** Invoke an operation on a set of mbeans. 

  101.      * 

  102.      * @param mbeans List of ObjectNames

  103.      * @param operation Operation to perform. Typically "init" "start" "stop" or "destroy"

  104.      * @param failFirst Behavior in case of exceptions - if false we'll ignore

  105.      *      errors

  106.      * @throws Exception

  107.      */ 

  108.     public void invoke( List mbeans, String operation, boolean failFirst )

  109.             throws Exception;

  110. 

  111.     /** Register a bean by creating a modeler mbean and adding it to the 

  112.      * MBeanServer.

  113.      * 

  114.      * If metadata is not loaded, we'll look up and read a file named

  115.      * "mbeans-descriptors.ser" or "mbeans-descriptors.xml" in the same package

  116.      * or parent.

  117.      *

  118.      * If the bean is an instance of DynamicMBean. it's metadata will be converted

  119.      * to a model mbean and we'll wrap it - so modeler services will be supported

  120.      *

  121.      * If the metadata is still not found, introspection will be used to extract

  122.      * it automatically. 

  123.      * 

  124.      * If an mbean is already registered under this name, it'll be first

  125.      * unregistered.

  126.      * 

  127.      * If the component implements MBeanRegistration, the methods will be called.

  128.      * If the method has a method "setRegistry" that takes a RegistryMBean as

  129.      * parameter, it'll be called with the current registry.

  130.      * 

  131.      *

  132.      * @param bean Object to be registered

  133.      * @param oname Name used for registration

  134.      * @param type The type of the mbean, as declared in mbeans-descriptors. If

  135.      * null, the name of the class will be used. This can be used as a hint or

  136.      * by subclasses.

  137.      *

  138.      * @since 1.1

  139.      */ 

  140.     public void registerComponent(Object bean, String oname, String type)

  141.            throws Exception;

  142. 

  143.     /** Unregister a component. We'll first check if it is registered,

  144.      * and mask all errors. This is mostly a helper.

  145.      * 

  146.      * @param oname

  147.      * 

  148.      * @since 1.1

  149.      */ 

  150.     public void unregisterComponent( String oname );

  151. 

  152. 

  153.      /** Return an int ID for faster access. Will be used for notifications

  154.       * and for other operations we want to optimize. 

  155.       *

  156.       * @param domain Namespace 

  157.       * @param name  Type of the notification

  158.       * @return  An unique id for the domain:name combination

  159.       * @since 1.1

  160.       */

  161.     public int getId( String domain, String name);

  162. 

  163. 

  164.     /** Reset all metadata cached by this registry. Should be called 

  165.      * to support reloading. Existing mbeans will not be affected or modified.

  166.      * 

  167.      * It will be called automatically if the Registry is unregistered.

  168.      * @since 1.1

  169.      */ 

  170.     public void stop();

  171. 

  172.     /** Load descriptors. The source can be a File, URL pointing to an

  173.      * mbeans-descriptors.xml.

  174.      * 

  175.      * Also ( experimental for now ) a ClassLoader - in which case META-INF/ will

  176.      * be used.

  177.      * 

  178.      * @param source

  179.      */ 

  180.     public void loadMetadata(Object source ) throws Exception;

  181. }