DescriptorKey (Java Platform SE 6) - JavaTM 2 Platform Standard Edition 6.0 API 规范中文版

概述

软件包

类

使用

树

已过时

索引

帮助

Java^TM Platform
Standard Ed. 6

上一个类 下一个类

框架 无框架

摘要：必需 | 可选

详细信息：元素

javax.management
注释类型 DescriptorKey

@Documented @Retention(value=RUNTIME) @Target(value=METHOD) public @interface DescriptorKey

描述注释元素与 Descriptor 中字段之间关联方式的元注释。它可以是 MBean 的 Descriptor，也可以是 MBean 中属性、操作或构造方法的 Descriptor，还可以是操作或构造方法的参数的 Descriptor。

考虑下例中的注释：

 @Documented
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Units {
     @DescriptorKey("units")
     String value();
 }

以及注释的这种用法：

public interface CacheControlMBean {
@Units("bytes")
public long getCacheSize();
 }

当 Standard MBean 由 CacheControlMBean 生成时，通常的规则意味着它将有一个称为 CacheSize 的类型为 long 的属性。在给定上述定义的情况下，@Units 属性将确保此属性的 MBeanAttributeInfo 将具有一个 Descriptor，该 Descriptor 有一个称为 units 的字段，且其相应的值为 bytes。

类似地，如果注释的形式如下：

 @Documented
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Units {
     @DescriptorKey("units")
     String value();

     @DescriptorKey("descriptionResourceKey")
     String resourceKey() default "";

     @DescriptorKey("descriptionResourceBundleBaseName")
     String resourceBundleBaseName() default "";
 }

且用法如下：

public interface CacheControlMBean {
@Units("bytes",
resourceKey="bytes.key",
resourceBundleBaseName="com.example.foo.MBeanResources")
public long getCacheSize();
 }

则得到的 Descriptor 将包含以下字段：

名称	值
units	"bytes"
descriptionResourceKey	"bytes.key"
descriptionResourceBundleBaseName	"com.example.foo.MBeanResources"

@Units 之类的注释可以应用于：

Standard MBean 或 MXBean 接口；
此类接口中的方法；
当某方法是一个操作（不是属性的获取方法或设置方法）时，Standard MBean 或 MXBean 接口中该方法的参数；
在实现 Standard MBean 或 MXBean 的类中的公共构造方法；
此类构造方法中的参数。

忽略注释的其他用途。

只在定义 Standard MBean 或 MXBean 的管理接口的具体接口上检查接口注释，而不在其父接口上检查。只在方法出现的最具体的接口中检查方法注释；换句话说，如果子接口重写了父接口中的方法，则只考虑子接口中该方法中的 @DescriptorKey 注释。

由同一个程序元素上的不同注释提供的 Descriptor 字段必须一致。也就是说，两个不同注释或同一注释的两个成员不得为同一 Descriptor 字段定义不同的值。获取方法上的注释字段也必须与相应设置方法上的注释字段一致。

从这些注释中得到的 Descriptor 将与实现提供的任何 Descriptor 字段合并，如 MBean 的 immutableInfo 字段。注释中的字段必须与实现提供的这些字段一致。

要转换为描述符字段的注释元素可以是 Java 语言允许的任何类型，注释或注释数组除外。字段值由以下注释元素的值导出：

注释元素	描述符字段
基本类型值（`5`、`false` 等）	包装值（`Integer.valueOf(5)`、`Boolean.FALSE` 等）
类常量（如 `Thread.class`）	`Class.getName()` 得到的类名称（如 `"java.lang.Thread"`）
枚举常量（如 `ElementType.FIELD`）	`Enum.name()` 得到的常量名称（如 `"FIELD"`）
类常量或枚举常量组成的数组	将这些规则应用于每个元素而派生的字符串数组
任何其他类型的值（`String`、`String[]`、`int[]` 等）	相同的值