jdk/src/share/classes/javax/management/ObjectNameTemplate.java
changeset 1700 4506662fb2ee
equal deleted inserted replaced
1699:3611e5fd6da5 1700:4506662fb2ee
       
     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 }