001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018
019 package org.apache.commons.modeler;
020
021
022 import java.util.List;
023
024 /**
025 * Interface for modeler MBeans.
026 *
027 * This is the main entry point into modeler. It provides methods to create
028 * and manipulate model mbeans and simplify their use.
029 *
030 * Starting with version 1.1, this is no longer a singleton and the static
031 * methods are strongly deprecated. In a container environment we can expect
032 * different applications to use different registries.
033 *
034 * @author Craig R. McClanahan
035 * @author Costin Manolache
036 *
037 * @since 1.1
038 */
039 public interface RegistryMBean {
040
041 /**
042 * Load an extended mlet file. The source can be an URL, File or
043 * InputStream.
044 *
045 * All mbeans will be instantiated, registered and the attributes will be
046 * set. The result is a list of ObjectNames.
047 *
048 * @param source InputStream or URL of the file
049 * @param cl ClassLoader to be used to load the mbeans, or null to use the
050 * default JMX mechanism ( i.e. all registered loaders )
051 * @return List of ObjectName for the loaded mbeans
052 * @throws Exception
053 *
054 * @since 1.1
055 */
056 public List loadMBeans( Object source, ClassLoader cl ) throws Exception;
057
058 /** Invoke an operation on a set of mbeans.
059 *
060 * @param mbeans List of ObjectNames
061 * @param operation Operation to perform. Typically "init" "start" "stop" or "destroy"
062 * @param failFirst Behavior in case of exceptions - if false we'll ignore
063 * errors
064 * @throws Exception
065 */
066 public void invoke( List mbeans, String operation, boolean failFirst )
067 throws Exception;
068
069 /** Register a bean by creating a modeler mbean and adding it to the
070 * MBeanServer.
071 *
072 * If metadata is not loaded, we'll look up and read a file named
073 * "mbeans-descriptors.ser" or "mbeans-descriptors.xml" in the same package
074 * or parent.
075 *
076 * If the bean is an instance of DynamicMBean. it's metadata will be converted
077 * to a model mbean and we'll wrap it - so modeler services will be supported
078 *
079 * If the metadata is still not found, introspection will be used to extract
080 * it automatically.
081 *
082 * If an mbean is already registered under this name, it'll be first
083 * unregistered.
084 *
085 * If the component implements MBeanRegistration, the methods will be called.
086 * If the method has a method "setRegistry" that takes a RegistryMBean as
087 * parameter, it'll be called with the current registry.
088 *
089 *
090 * @param bean Object to be registered
091 * @param oname Name used for registration
092 * @param type The type of the mbean, as declared in mbeans-descriptors. If
093 * null, the name of the class will be used. This can be used as a hint or
094 * by subclasses.
095 *
096 * @since 1.1
097 */
098 public void registerComponent(Object bean, String oname, String type)
099 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 }