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    }