JMXConnector


1   package org.apache.tools.ant.taskdefs.optional.jmx.connector;
2   
3   /*
4    * ============================================================================
5    *                   The Apache Software License, Version 1.1
6    * ============================================================================
7    * 
8    *    Copyright (C) 2000-2002 The Apache Software Foundation. All
9    *    rights reserved.
10   * 
11   * Redistribution and use in source and binary forms, with or without modifica-
12   * tion, are permitted provided that the following conditions are met:
13   * 
14   * 1. Redistributions of  source code must  retain the above copyright  notice,
15   *    this list of conditions and the following disclaimer.
16   * 
17   * 2. Redistributions in binary form must reproduce the above copyright notice,
18   *    this list of conditions and the following disclaimer in the documentation
19   *    and/or other materials provided with the distribution.
20   * 
21   * 3. The end-user documentation included with the redistribution, if any, must
22   *    include  the following  acknowledgment:  "This product includes  software
23   *    developed  by the  Apache Software Foundation  (http://www.apache.org/)."
24   *    Alternately, this  acknowledgment may  appear in the software itself,  if
25   *    and wherever such third-party acknowledgments normally appear.
26   * 
27   * 4. The names "Ant" and  "Apache Software Foundation"  must not be used to
28   *    endorse  or promote  products derived  from this  software without  prior
29   *    written permission. For written permission, please contact
30   *    apache@apache.org.
31   * 
32   * 5. Products  derived from this software may not  be called "Apache", nor may
33   *    "Apache" appear  in their name,  without prior written permission  of the
34   *    Apache Software Foundation.
35   * 
36   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES,
37   * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
38   * FITNESS  FOR A PARTICULAR  PURPOSE ARE  DISCLAIMED.  IN NO  EVENT SHALL  THE
39   * APACHE SOFTWARE  FOUNDATION  OR ITS CONTRIBUTORS  BE LIABLE FOR  ANY DIRECT,
40   * INDIRECT, INCIDENTAL, SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL  DAMAGES (INCLU-
41   * DING, BUT NOT LIMITED TO, PROCUREMENT  OF SUBSTITUTE GOODS OR SERVICES; LOSS
42   * OF USE, DATA, OR  PROFITS; OR BUSINESS  INTERRUPTION)  HOWEVER CAUSED AND ON
43   * ANY  THEORY OF LIABILITY,  WHETHER  IN CONTRACT,  STRICT LIABILITY,  OR TORT
44   * (INCLUDING  NEGLIGENCE OR  OTHERWISE) ARISING IN  ANY WAY OUT OF THE  USE OF
45   * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
46   * 
47   * This software  consists of voluntary contributions made  by many individuals
48   * on behalf of the  Apache Software Foundation.  For more  information  on the 
49   * Apache Software Foundation, please see <http://www.apache.org/>.
50   *
51   */
52  
53  import java.util.Hashtable  ;
54  import javax.management.MBeanServer  ;
55  import javax.management.ObjectName  ;
56  
57  /**
58   * Interface that provides access to a remote JMX server.
59   * JMXConnector provides a consistent interface for functions 
60   * required by the Ant JMX tasks not current covered 
61   * adequately by the JMX specification.</p>
62   *
63   * Implementations of this interface are instantiated by 
64   * <code>JMXConnectorFactory</code>. JMXConnectorFactory will locate 
65   * the correct JMXConnector implementation based on the value of the 
66   * serverType attribute that appears on the ANT task.</p>
67   *
68   * JMXConnectorFactory locates the JMXConnector implementation
69   * by first using the serverType argument as part of the 
70   * package name according to the following template:
71   * org.apache.tools.ant.taskdefs.optional.jmx.connector.<serverType>.Connector</p>
72   *
73   * If this technique fails to find a class that implements JMXConnector,
74   * then it is assumed that serverType is the fully qualified
75   * class name for the JMXConnector implementation 
76   * (e.g. serverType = org.someone.MyJMXServer).
77   * 
78   *
79   *
80   * @author  <a HREF="mailto:bdueck@yahoo.com">Brian Dueck</a>
81   * @version $Id: JMXConnector.java,v 1.4 2003/05/28 22:28:26 bdueck Exp $
82   */
83  public interface JMXConnector {
84  
85      /**
86       * Returns a base set of initial context properties that
87       * apply to this JMXServer adaptor. These properties
88       * will be used in conjuntion with additional properties 
89       * obtained from the task - for example, user and password
90       * information.
91       * 
92       * Prior to invoking this method, the caller will extract
93       * information from the Ant task and place these values in 
94       * the property list according to the following mapping:</p>
95       *
96       * Context.PROVIDER_URL = providerUrl</p>
97       * Context.SECURITY_PRINCIPAL = user</p>
98       * Context.SECURITY_CREDENTIALS = password</p>
99       *
100      * The implementation of this method may examine/modify/delete/add 
101      * to the properties as appropriate for the implementation.</p>
102      *
103      * Minimally, the implementation is expected to add the
104      * Context.INITIAL_CONTEXT_FACTORY value that is appropriate
105      * for this JMXConnector implementation. For example:</p>
106      *
107      * contextProps.put(javax.naming.Context.INITIAL_CONTEXT_FACTORY, 
108      *        weblogic.jndi.WLInitialContextFactory.class.getName());</p>
109      *
110      * After this method returns, the caller may further 
111      * augment the properties as required - but typically 
112      * does not.</p>
113      *
114      * These resulting properties will be passed to the 
115      * getMBeanServer() method of this interface after 
116      * this call returns.</p>
117      */
118     public Hashtable   getInitialContextProperties(Hashtable   contextProps);
119 
120     /**
121      * Returns a base set of initial context properties that
122      * apply to this JMXServer adaptor. These properties
123      * will be used in conjuntion with additional properties 
124      * obtained from the task - for example, user and password
125      * information.
126      *
127      * This is a convenience wrapper to allow minimimum set of properties to be
128      * specified without manipulating the hashtable directly.
129      * <strong>NOTE: If any of these values are null, they will be ignored.</strong>
130      *
131      */
132     public Hashtable   getInitialContextProperties(String   providerUrl, String   user, String   password);
133     
134     /**
135      * Connects to a JMX server and returns the MBeanServer to
136      * use during task execution. The caller is responsible
137      * for invoking this method prior to invoking createMBean()
138      * or getActiveDomain() methods on this interface.
139      *
140      * The getInitialContextProperties() method will be invoked
141      * prior to this method.
142      *
143      * @param context The set of properties used to locate
144      * and connect to the JMX server.
145      * @param jndiLookupName The JNDI entry name for the MBeanServer.
146      * @raise BuildException if an error occurs attempting to login.
147      */        
148     public MBeanServer   getMBeanServer(Hashtable   contextProps, String   jndiLookupName) throws org.apache.tools.ant.BuildException;
149 
150 
151     /**
152      * Creates & registers an MBean with an MBeanServer.
153      * While MBeanServer does have a standard createMBean() method,
154      * it is insufficiently supported in some implementations and
155      * therefore can't be used directly all the time.
156      * If a JMX server does not support MBean creation and registration,
157      * this method should always throw javax.management.MBeanRegistrationException,
158      * causing the task to fail.
159      *
160      * @param type The type or classname of the MBean to create.
161      * @param objectName The name of the MBean to create.
162      * @param mbserver The server where the new MBean will be created.
163      * @raises javax.management.MBeanRegistrationException If an error
164      * occurs creating the MBean.
165      */
166     public ObjectName   createMBean(String   type, ObjectName   objectName, MBeanServer   mbserver) throws javax.management.MBeanRegistrationException  ;
167     
168     
169     /**
170      * Returns the active/default domain for this JMXServer.
171      */
172     public String   getActiveDomain(MBeanServer   mbserver);
173     
174 }
175 
176 /*
177  * $Log: JMXConnector.java,v $
178  * Revision 1.4  2003/05/28 22:28:26  bdueck
179  * *** empty log message ***
180  *
181  * Revision 1.3  2003/04/21 15:29:39  bdueck
182  * Various changes in preparation for version 1.2.
183  *
184  * Revision 1.2  2003/04/01 22:14:06  bdueck
185  * Added convenience version of getInitialContextProperties().
186  *
187  * Revision 1.1  2003/01/17 12:34:00  bdueck
188  * Initial check-in
189  *
190  *
191  */
192
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags