RegistryMBean


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