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 &#64;MBean}</code>

    39  * annotation.</li>

    40  *   <li>Java class annotated with {@link javax.management.MXBean &#64;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 }