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: package org.apache.commons.modeler;
019:
020: import java.util.List;
021:
022: /**
023: * Interface for modeler MBeans.
024: *
025: * This is the main entry point into modeler. It provides methods to create
026: * and manipulate model mbeans and simplify their use.
027: *
028: * Starting with version 1.1, this is no longer a singleton and the static
029: * methods are strongly deprecated. In a container environment we can expect
030: * different applications to use different registries.
031: *
032: * @author Craig R. McClanahan
033: * @author Costin Manolache
034: *
035: * @since 1.1
036: */
037: public interface RegistryMBean {
038:
039: /**
040: * Load an extended mlet file. The source can be an URL, File or
041: * InputStream.
042: *
043: * All mbeans will be instantiated, registered and the attributes will be
044: * set. The result is a list of ObjectNames.
045: *
046: * @param source InputStream or URL of the file
047: * @param cl ClassLoader to be used to load the mbeans, or null to use the
048: * default JMX mechanism ( i.e. all registered loaders )
049: * @return List of ObjectName for the loaded mbeans
050: * @throws Exception
051: *
052: * @since 1.1
053: */
054: public List loadMBeans(Object source, ClassLoader cl)
055: throws Exception;
056:
057: /** Invoke an operation on a set of mbeans.
058: *
059: * @param mbeans List of ObjectNames
060: * @param operation Operation to perform. Typically "init" "start" "stop" or "destroy"
061: * @param failFirst Behavior in case of exceptions - if false we'll ignore
062: * errors
063: * @throws Exception
064: */
065: public void invoke(List mbeans, String operation, boolean failFirst)
066: throws Exception;
067:
068: /** Register a bean by creating a modeler mbean and adding it to the
069: * MBeanServer.
070: *
071: * If metadata is not loaded, we'll look up and read a file named
072: * "mbeans-descriptors.ser" or "mbeans-descriptors.xml" in the same package
073: * or parent.
074: *
075: * If the bean is an instance of DynamicMBean. it's metadata will be converted
076: * to a model mbean and we'll wrap it - so modeler services will be supported
077: *
078: * If the metadata is still not found, introspection will be used to extract
079: * it automatically.
080: *
081: * If an mbean is already registered under this name, it'll be first
082: * unregistered.
083: *
084: * If the component implements MBeanRegistration, the methods will be called.
085: * If the method has a method "setRegistry" that takes a RegistryMBean as
086: * parameter, it'll be called with the current registry.
087: *
088: *
089: * @param bean Object to be registered
090: * @param oname Name used for registration
091: * @param type The type of the mbean, as declared in mbeans-descriptors. If
092: * null, the name of the class will be used. This can be used as a hint or
093: * by subclasses.
094: *
095: * @since 1.1
096: */
097: public void registerComponent(Object bean, String oname, String type)
098: throws Exception;
099:
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: /** Return an int ID for faster access. Will be used for notifications
110: * and for other operations we want to optimize.
111: *
112: * @param domain Namespace
113: * @param name Type of the notification
114: * @return An unique id for the domain:name combination
115: * @since 1.1
116: */
117: public int getId(String domain, String name);
118:
119: /** Reset all metadata cached by this registry. Should be called
120: * to support reloading. Existing mbeans will not be affected or modified.
121: *
122: * It will be called automatically if the Registry is unregistered.
123: * @since 1.1
124: */
125: public void stop();
126:
127: /** Load descriptors. The source can be a File, URL pointing to an
128: * mbeans-descriptors.xml.
129: *
130: * Also ( experimental for now ) a ClassLoader - in which case META-INF/ will
131: * be used.
132: *
133: * @param source
134: */
135: public void loadMetadata(Object source) throws Exception;
136: }
|