|
1 /* |
|
2 * Copyright 2008 Sun Microsystems, Inc. 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. Sun designates this |
|
8 * particular file as subject to the "Classpath" exception as provided |
|
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
|
22 * CA 95054 USA or visit www.sun.com if you need additional information or |
|
23 * have any questions. |
|
24 */ |
|
25 package javax.management; |
|
26 |
|
27 import java.lang.annotation.Documented; |
|
28 import java.lang.annotation.ElementType; |
|
29 import java.lang.annotation.Retention; |
|
30 import java.lang.annotation.RetentionPolicy; |
|
31 import java.lang.annotation.Target; |
|
32 |
|
33 /** |
|
34 * Annotation to allow an MBean to provide its name. |
|
35 * This annotation can be used on the following types: |
|
36 * <ul> |
|
37 * <li>MBean or MXBean Java interface.</li> |
|
38 * <li>Java class annotated with {@link javax.management.MBean @MBean}</code> |
|
39 * annotation.</li> |
|
40 * <li>Java class annotated with {@link javax.management.MXBean @MXBean}</code> |
|
41 * annotation.</li> |
|
42 * </ul> |
|
43 * |
|
44 * <p>The value of this annotation is used to build the <code>ObjectName</code> |
|
45 * when instances of the annotated type are registered in |
|
46 * an <code>MBeanServer</code> and no explicit name is given to the |
|
47 * {@code createMBean} or {@code registerMBean} method (the {@code ObjectName} |
|
48 * is {@code null}).</p> |
|
49 * |
|
50 * <p>For Dynamic MBeans, which define their own {@code MBeanInfo}, you can |
|
51 * produce the same effect as this annotation by including a field |
|
52 * <a href="Descriptor.html#objectNameTemplate">{@code objectNameTemplate}</a> |
|
53 * in the {@link Descriptor} for the {@code MBeanInfo} returned by |
|
54 * {@link DynamicMBean#getMBeanInfo()}.</p> |
|
55 * |
|
56 * <p>For Standard MBeans and MXBeans, this annotation automatically produces |
|
57 * an {@code objectNameTemplate} field in the {@code Descriptor}.</p> |
|
58 * |
|
59 * <p>The template can contain variables so that the name of the MBean |
|
60 * depends on the value of one or more of its attributes. |
|
61 * A variable that identifies an MBean attribute is of the form |
|
62 * <code>{<em>attribute name</em>}</code>. For example, to make an MBean name |
|
63 * depend on the <code>Name</code> attribute, use the variable |
|
64 * <code>{Name}</code>. Attribute names are case sensitive. |
|
65 * Naming attributes can be of any type. The <code>String</code> returned by |
|
66 * <code>toString()</code> is included in the constructed name.</p> |
|
67 * |
|
68 * <p>If you need the attribute value to be quoted |
|
69 * by a call to {@link ObjectName#quote(String) ObjectName.quote}, |
|
70 * surround the variable with quotes. Quoting only applies to key values. |
|
71 * For example, <code>@ObjectNameTemplate("java.lang:type=MemoryPool,name=\"{Name}\"")</code>, |
|
72 * quotes the <code>Name</code> attribute value. You can notice the "\" |
|
73 * character needed to escape a quote within a <code>String</code>. A name |
|
74 * produced by this template might look like |
|
75 * {@code java.lang:type=MemoryPool,name="Code Cache"}.</p> |
|
76 * |
|
77 * <p>Variables can be used anywhere in the <code>String</code>. |
|
78 * Be sure to make the template derived name comply with |
|
79 * {@link ObjectName ObjectName} syntax.</p> |
|
80 * |
|
81 * <p>If an MBean is registered with a null name and it implements |
|
82 * {@link javax.management.MBeanRegistration MBeanRegistration}, then |
|
83 * the computed name is provided to the <code>preRegister</code> method. |
|
84 * Similarly, |
|
85 * if the MBean uses <a href="MBeanRegistration.html#injection">resource |
|
86 * injection</a> to discover its name, it is the computed name that will |
|
87 * be injected.</p> |
|
88 * <p>All of the above can be used with the {@link StandardMBean} class and |
|
89 * the annotation is effective in that case too.</p> |
|
90 * <p>If any exception occurs (such as unknown attribute, invalid syntax or |
|
91 * exception |
|
92 * thrown by the MBean) when the name is computed it is wrapped in a |
|
93 * <code>NotCompliantMBeanException</code>.</p> |
|
94 * <p>Some ObjectName template examples: |
|
95 * <ul><li>"com.example:type=Memory". Fixed ObjectName. Used to name a |
|
96 * singleton MBean.</li> |
|
97 * <li>"com.example:type=MemoryPool,name={Name}". Variable ObjectName. |
|
98 * <code>Name</code> attribute is retrieved to compose the <code>name</code> |
|
99 * key value.</li> |
|
100 * <li>"com.example:type=SomeType,name={InstanceName},id={InstanceId}". |
|
101 * Variable ObjectName. |
|
102 * <code>InstanceName</code> and <code>InstanceId</code> attributes are |
|
103 * retrieved to compose respectively |
|
104 * the <code>name</code> and <code>id</code> key values.</li> |
|
105 * <li>"com.example:type=OtherType,name=\"{ComplexName}\"". Variable ObjectName. |
|
106 * <code>ComplexName</code> attribute is retrieved to compose the |
|
107 * <code>name</code> key quoted value.</li> </li> |
|
108 * <li>"com.example:{TypeKey}=SomeOtherType". Variable ObjectName. |
|
109 * <code>TypeKey</code> attribute is retrieved to compose the |
|
110 * first key name.</li> |
|
111 * * <li>"{Domain}:type=YetAnotherType". Variable ObjectName. |
|
112 * <code>Domain</code> attribute is retrieved to compose the |
|
113 * management domain.</li> |
|
114 * <li>"{Naming}". Variable ObjectName. |
|
115 * <code>Naming</code> attribute is retrieved to compose the |
|
116 * complete name.</li> |
|
117 * </ul> |
|
118 * </p> |
|
119 */ |
|
120 @Documented |
|
121 @Retention(RetentionPolicy.RUNTIME) |
|
122 @Target(ElementType.TYPE) |
|
123 public @interface ObjectNameTemplate { |
|
124 |
|
125 /** |
|
126 * The MBean name template. |
|
127 * @return The MBean name template. |
|
128 */ |
|
129 @DescriptorKey("objectNameTemplate") |
|
130 public String value(); |
|
131 } |