View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  
19  package org.apache.commons.modeler;
20  
21  
22  import java.util.List;
23  
24  /***
25   * Interface for modeler MBeans.
26   * 
27   * This is the main entry point into modeler. It provides methods to create
28   * and manipulate model mbeans and simplify their use.
29   *
30   * Starting with version 1.1, this is no longer a singleton and the static
31   * methods are strongly deprecated. In a container environment we can expect
32   * different applications to use different registries.
33   * 
34   * @author Craig R. McClanahan
35   * @author Costin Manolache
36   * 
37   * @since 1.1
38   */
39  public interface RegistryMBean {
40  
41      /*** 
42       * Load an extended mlet file. The source can be an URL, File or
43       * InputStream. 
44       * 
45       * All mbeans will be instantiated, registered and the attributes will be 
46       * set. The result is a list of ObjectNames.
47       *
48       * @param source InputStream or URL of the file
49       * @param cl ClassLoader to be used to load the mbeans, or null to use the
50       *        default JMX mechanism ( i.e. all registered loaders )
51       * @return List of ObjectName for the loaded mbeans
52       * @throws Exception
53       * 
54       * @since 1.1
55       */ 
56      public List loadMBeans( Object source, ClassLoader cl ) throws Exception;
57  
58      /*** Invoke an operation on a set of mbeans. 
59       * 
60       * @param mbeans List of ObjectNames
61       * @param operation Operation to perform. Typically "init" "start" "stop" or "destroy"
62       * @param failFirst Behavior in case of exceptions - if false we'll ignore
63       *      errors
64       * @throws Exception
65       */ 
66      public void invoke( List mbeans, String operation, boolean failFirst )
67              throws Exception;
68  
69      /*** Register a bean by creating a modeler mbean and adding it to the 
70       * MBeanServer.
71       * 
72       * If metadata is not loaded, we'll look up and read a file named
73       * "mbeans-descriptors.ser" or "mbeans-descriptors.xml" in the same package
74       * or parent.
75       *
76       * If the bean is an instance of DynamicMBean. it's metadata will be converted
77       * to a model mbean and we'll wrap it - so modeler services will be supported
78       *
79       * If the metadata is still not found, introspection will be used to extract
80       * it automatically. 
81       * 
82       * If an mbean is already registered under this name, it'll be first
83       * unregistered.
84       * 
85       * If the component implements MBeanRegistration, the methods will be called.
86       * If the method has a method "setRegistry" that takes a RegistryMBean as
87       * parameter, it'll be called with the current registry.
88       * 
89       *
90       * @param bean Object to be registered
91       * @param oname Name used for registration
92       * @param type The type of the mbean, as declared in mbeans-descriptors. If
93       * null, the name of the class will be used. This can be used as a hint or
94       * by subclasses.
95       *
96       * @since 1.1
97       */ 
98      public void registerComponent(Object bean, String oname, String type)
99             throws Exception;
100 
101     /*** Unregister a component. We'll first check if it is registered,
102      * and mask all errors. This is mostly a helper.
103      * 
104      * @param oname
105      * 
106      * @since 1.1
107      */ 
108     public void unregisterComponent( String oname );
109 
110 
111      /*** Return an int ID for faster access. Will be used for notifications
112       * and for other operations we want to optimize. 
113       *
114       * @param domain Namespace 
115       * @param name  Type of the notification
116       * @return  An unique id for the domain:name combination
117       * @since 1.1
118       */
119     public int getId( String domain, String name);
120 
121 
122     /*** Reset all metadata cached by this registry. Should be called 
123      * to support reloading. Existing mbeans will not be affected or modified.
124      * 
125      * It will be called automatically if the Registry is unregistered.
126      * @since 1.1
127      */ 
128     public void stop();
129 
130     /*** Load descriptors. The source can be a File, URL pointing to an
131      * mbeans-descriptors.xml.
132      * 
133      * Also ( experimental for now ) a ClassLoader - in which case META-INF/ will
134      * be used.
135      * 
136      * @param source
137      */ 
138     public void loadMetadata(Object source ) throws Exception;
139 }