CustomMBeanOperationsMBean


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package com.sun.enterprise.admin.mbeans.custom;
25  import java.util.Map  ;
26  import javax.management.MBeanInfo  ;
27  
28  /** Interface that defines the behavior of modifying the configuration in the admin server
29   * for custom mbeans. Though this is mostly similar to a J2EE application or
30   * module deployment, in order to factor out the Custom MBean Configuration changes,
31   * this interface is defined. Note that <i> target </i> is a central concept in the
32   * deployment of applications and mbeans. In all the interface methods that are defined here,
33   * the target must be a server or a cluster. A special target with name "server"
34   * defines a domain. The handling of targets is defined in the Custom MBean design
35   * document.
36   * @since SJSAS9.0
37   */
38  public interface CustomMBeanOperationsMBean {
39      /** Creates an MBean with given className in given target. Results in the call to
40       * #createMBean(String, String, Map<String, String>, Map<String, String>).
41       * The Map<String, String> will be empty, so will be Map<String, String>.
42       * @param target String representing the target
43       * @param className String representing the implementation class
44       */
45      public String   createMBean(String   target, String   className) throws CustomMBeanException;
46  
47      /** Creates an MBean with given className in given target. Results in the call to
48       * #createMBean(String, String, Map<String, String>, Map<String, String>).
49       * The Map<String, String> should contain the 0 or more items from the @link{CustomMBeanConstants}
50       * class.
51       * <ul>
52       * <li>class-name of the custom mbean, which is mandatory</li>
53       * <li>name of the custom mbean</li>
54       * <li>object-name of the custom mbean</li>
55       * </ul>
56       * @param target String representing the target
57       * @param params a Map<String, String> explained above
58       */
59      public String   createMBean(String   target, Map  <String  , String  > params) throws CustomMBeanException;
60  
61      /** Creates an MBean with given class-name in the given target's configuration.
62       * The class-name may not be null. The class must represent a valid JMX MBean implementation.
63       * All the standard requirements must be fulfilled by the given class. Here is a list of 
64       * requirements from the given class-name. It is by no means an exhaustive one. Refer to
65       * the design document for the complete list.
66       * <ul>
67       * <li> The class-name may not be null </li>
68       * <li> It must be instantiable with a default constructor </li>
69       * <li> The class bits must be available in order to be loaded dynamically, knowing full name </li>
70       * Refer to the class Javadoc for a note on target.
71       * The various mappings in the params map are as follows:
72       * <ul> <li> String CustomMBeanConstants.NAME_KEY -> name of the MBean </li>
73       * <li> Mandatory String CustomMBeanConstants.IMPL_CLASS_NAME_KEY -> the actual class </li>
74       * <li> String CustomMBeanConstants.OBJECT_NAME_KEY -> intended ObjectName of the MBean </li> </ul>
75       *
76       * @param target String representing target where the MBean would be instantiated. The value null represents
77       * the domain as the target
78       * @param params a Map with mappings between String and String containing various configuration parameters
79       * @param attributes a Map between two Strings repsenting name of an attribute and String representation of its value.
80       * </ul>
81       * @throws All the createMBean methods in this class throw CustomMBeanException if the custom MBean definition
82       * is invalid or if we can guarantee that the registration of the MBean at a latter point in time without
83       * any change in the runtime state of the system would be successful.
84       * @return the <i> name </i> of the MBean as determined by the backend. The name returned is
85       * guaranteed to be unique amongst all application sub-elements.
86       */
87      public String   createMBean(String   target, Map  <String  , String  > params, Map  <String  , String  > attributes) throws CustomMBeanException;
88      
89      /** Deletes the MBean with the given name from the configuration and optionally deletes the corresponding
90       * classes from the file system. The deletion of classes should not be relied upon by the clients.
91       * Refer to the design document for exact semantics of this method.
92       */
93      public String   deleteMBean(String   target, String   name) throws CustomMBeanException;
94      
95      /** Creates a reference to the given MBean. It is a misnomer in that it actually creates an application-ref
96       * sub-element in a server, but it is named so for functional clarity. This is available only in 
97       * EE of appserver because it is against a precedent to create references in PE.
98       * @param target String representing the target, could be cluster or a server instance. A null value represents the domain itself.
99       * @param ref String representing the <i> name </i> of the custom MBean definition
100      * @throws CustomMBeanException if the custom MBean reference could not be created for some reason
101      */
102     public void createMBeanRef(String   target, String   ref) throws CustomMBeanException;
103 
104     /** Deletes a reference to the given MBean from a server or cluster. It is a misnomer in that it actually deletes an application-ref
105      * sub-element from a server, but it is named so for functional clarity. This is available only in 
106      * EE of appserver because it is against a precedent to delete references in PE.
107      * @param target String representing the target, could be cluster or a server instance
108      * @param ref String representing the <i> name </i> of the custom MBean definition, which is same as
109      * as the referenced name
110      * @throws CustomMBeanException if the custom MBean reference could not be deleted for some reason
111      */
112     public void deleteMBeanRef(String   target, String   ref) throws CustomMBeanException;
113  
114     /**
115      * Return the MBeanInfo of a given Custom MBean.  
116      * The MBean must be loadable from the standard App Server location.
117      * The code does this:
118      * <ul>
119      * <li>Register the MBean in the MBeanServer
120      * <li>Fetch and save the MBeanInfo
121      * <li>Unregister the MBean
122      * </ul>
123      * Note that if the MBean can't be deployed successfully then this method won't work.
124      * @param classname 
125      * @throws com.sun.enterprise.admin.mbeans.custom.CustomMBeanException 
126      * @return The MBeanInfo object
127      */
128      public MBeanInfo   getMBeanInfo(String   classname) throws CustomMBeanException;
129 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags