1 /* 2 * Copyright (c) 2002, 2008, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 27 package javax.management.remote; 28 29 import java.io.IOException; 30 import java.util.Map; 31 32 /** 33 * <p>MBean interface for connector servers. A JMX API connector server 34 * is attached to an MBean server, and establishes connections to that 35 * MBean server for remote clients.</p> 36 * 37 * <p>A newly-created connector server is <em>inactive</em>, and does 38 * not yet listen for connections. Only when its {@link #start start} 39 * method has been called does it start listening for connections.</p> 40 * 41 * @since 1.5 42 */ 43 public interface JMXConnectorServerMBean { 44 /** 45 * <p>Activates the connector server, that is, starts listening for 46 * client connections. Calling this method when the connector 47 * server is already active has no effect. Calling this method 48 * when the connector server has been stopped will generate an 49 * {@link IOException}.</p> 50 * 51 * @exception IOException if it is not possible to start listening 52 * or if the connector server has been stopped. 53 * 54 * @exception IllegalStateException if the connector server has 55 * not been attached to an MBean server. 56 */ start()57 public void start() throws IOException; 58 59 /** 60 * <p>Deactivates the connector server, that is, stops listening for 61 * client connections. Calling this method will also close all 62 * client connections that were made by this server. After this 63 * method returns, whether normally or with an exception, the 64 * connector server will not create any new client 65 * connections.</p> 66 * 67 * <p>Once a connector server has been stopped, it cannot be started 68 * again.</p> 69 * 70 * <p>Calling this method when the connector server has already 71 * been stopped has no effect. Calling this method when the 72 * connector server has not yet been started will disable the 73 * connector server object permanently.</p> 74 * 75 * <p>If closing a client connection produces an exception, that 76 * exception is not thrown from this method. A {@link 77 * JMXConnectionNotification} with type {@link 78 * JMXConnectionNotification#FAILED} is emitted from this MBean 79 * with the connection ID of the connection that could not be 80 * closed.</p> 81 * 82 * <p>Closing a connector server is a potentially slow operation. 83 * For example, if a client machine with an open connection has 84 * crashed, the close operation might have to wait for a network 85 * protocol timeout. Callers that do not want to block in a close 86 * operation should do it in a separate thread.</p> 87 * 88 * @exception IOException if the server cannot be closed cleanly. 89 * When this exception is thrown, the server has already attempted 90 * to close all client connections. All client connections are 91 * closed except possibly those that generated exceptions when the 92 * server attempted to close them. 93 */ stop()94 public void stop() throws IOException; 95 96 /** 97 * <p>Determines whether the connector server is active. A connector 98 * server starts being active when its {@link #start start} method 99 * returns successfully and remains active until either its 100 * {@link #stop stop} method is called or the connector server 101 * fails.</p> 102 * 103 * @return true if the connector server is active. 104 */ isActive()105 public boolean isActive(); 106 107 /** 108 * <p>Inserts an object that intercepts requests for the MBean server 109 * that arrive through this connector server. This object will be 110 * supplied as the <code>MBeanServer</code> for any new connection 111 * created by this connector server. Existing connections are 112 * unaffected.</p> 113 * 114 * <p>This method can be called more than once with different 115 * {@link MBeanServerForwarder} objects. The result is a chain 116 * of forwarders. The last forwarder added is the first in the chain. 117 * In more detail:</p> 118 * 119 * <ul> 120 * <li><p>If this connector server is already associated with an 121 * <code>MBeanServer</code> object, then that object is given to 122 * {@link MBeanServerForwarder#setMBeanServer 123 * mbsf.setMBeanServer}. If doing so produces an exception, this 124 * method throws the same exception without any other effect.</p> 125 * 126 * <li><p>If this connector is not already associated with an 127 * <code>MBeanServer</code> object, or if the 128 * <code>mbsf.setMBeanServer</code> call just mentioned succeeds, 129 * then <code>mbsf</code> becomes this connector server's 130 * <code>MBeanServer</code>.</p> 131 * </ul> 132 * 133 * @param mbsf the new <code>MBeanServerForwarder</code>. 134 * 135 * @exception IllegalArgumentException if the call to {@link 136 * MBeanServerForwarder#setMBeanServer mbsf.setMBeanServer} fails 137 * with <code>IllegalArgumentException</code>. This includes the 138 * case where <code>mbsf</code> is null. 139 */ setMBeanServerForwarder(MBeanServerForwarder mbsf)140 public void setMBeanServerForwarder(MBeanServerForwarder mbsf); 141 142 /** 143 * <p>The list of IDs for currently-open connections to this 144 * connector server.</p> 145 * 146 * @return a new string array containing the list of IDs. If 147 * there are no currently-open connections, this array will be 148 * empty. 149 */ getConnectionIds()150 public String[] getConnectionIds(); 151 152 /** 153 * <p>The address of this connector server.</p> 154 * <p> 155 * The address returned may not be the exact original {@link JMXServiceURL} 156 * that was supplied when creating the connector server, since the original 157 * address may not always be complete. For example the port number may be 158 * dynamically allocated when starting the connector server. Instead the 159 * address returned is the actual {@link JMXServiceURL} of the 160 * {@link JMXConnectorServer}. This is the address that clients supply 161 * to {@link JMXConnectorFactory#connect(JMXServiceURL)}. 162 * </p> 163 * <p>Note that the address returned may be {@code null} if 164 * the {@code JMXConnectorServer} is not yet {@link #isActive active}. 165 * </p> 166 * 167 * @return the address of this connector server, or null if it 168 * does not have one. 169 */ getAddress()170 public JMXServiceURL getAddress(); 171 172 /** 173 * <p>The attributes for this connector server.</p> 174 * 175 * @return a read-only map containing the attributes for this 176 * connector server. Attributes whose values are not serializable 177 * are omitted from this map. If there are no serializable 178 * attributes, the returned map is empty. 179 */ getAttributes()180 public Map<String,?> getAttributes(); 181 182 /** 183 * <p>Returns a client stub for this connector server. A client 184 * stub is a serializable object whose {@link 185 * JMXConnector#connect(Map) connect} method can be used to make 186 * one new connection to this connector server.</p> 187 * 188 * <p>A given connector need not support the generation of client 189 * stubs. However, the connectors specified by the JMX Remote API do 190 * (JMXMP Connector and RMI Connector).</p> 191 * 192 * @param env client connection parameters of the same sort that 193 * can be provided to {@link JMXConnector#connect(Map) 194 * JMXConnector.connect(Map)}. Can be null, which is equivalent 195 * to an empty map. 196 * 197 * @return a client stub that can be used to make a new connection 198 * to this connector server. 199 * 200 * @exception UnsupportedOperationException if this connector 201 * server does not support the generation of client stubs. 202 * 203 * @exception IllegalStateException if the JMXConnectorServer is 204 * not started (see {@link JMXConnectorServerMBean#isActive()}). 205 * 206 * @exception IOException if a communications problem means that a 207 * stub cannot be created. 208 * 209 */ toJMXConnector(Map<String,?> env)210 public JMXConnector toJMXConnector(Map<String,?> env) 211 throws IOException; 212 } 213