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 }