Hycz's Blog

Life is a game. Why so serious?

Category Archives: Java

[转]Java Annotation入门

Java Annotation入门

作者:cleverpig

版权声明:本文可以自由转载,转载时请务必以超链接形式标明文章原始出处和作者信息及本声明
作者:cleverpig(作者的Blog:http://blog.matrix.org.cn/page/cleverpig)
原 文:[http://www.matrix.org.cn/resource/article/44/44048_Java+Annotation.html]http://www.matrix.org.cn/resource/article/44/44048_Java+Annotation.html[/url]
关键字:Java,annotation,标注

摘要:
本 文针对java初学者或者annotation初次使用者全面地说明了annotation的使用方法、定义方式、分类。初学者可以通过以上的说明制作简 单的annotation程序,但是对于一些高级的annotation应用(例如使用自定义annotation生成javabean映射xml文件) 还需要进一步的研究和探讨。涉及到深入annotation的内容,作者将在后文《Java Annotation高级应用》中谈到。

同时,annotation运行存在两种方式:运行时、编译时。上文中讨论的都是在运行时的annotation应用,但在编译时的annotation应用还没有涉及,

一、为什么使用Annotation:

在JAVA应用中,我们常遇到一些需要使用模版代码。例如,为了编写一个JAX-RPC web service,我们必须提供一对接口和实现作为模版代码。如果使用annotation对远程访问的方法代码进行修饰的话,这个模版就能够使用工具自动生成。
另 外,一些API需要使用与程序代码同时维护的附属文件。例如,JavaBeans需要一个BeanInfo Class与一个Bean同时使用/维护,而EJB则同样需要一个部署描述符。此时在程序中使用annotation来维护这些附属文件的信息将十分便利 而且减少了错误。

二、Annotation工作方式:

在5.0 版之前的Java平台已经具有了一些ad hoc annotation机制。比如,使用transient修饰符来标识一个成员变量在序列化子系统中应被忽略。而@deprecated这个 javadoc tag也是一个ad hoc annotation用来说明一个方法已过时。从Java5.0版发布以来,5.0平台提供了一个正式的annotation功能:允许开发者定义、使用 自己的annoatation类型。此功能由一个定义annotation类型的语法和一个描述annotation声明的语法,读取annotaion 的API,一个使用annotation修饰的class文件,一个annotation处理工具(apt)组成。
annotation并不直接影响代码语义,但是它能够工作的方式被看作类似程序的工具或者类库,它会反过来对正在运行的程序语义有所影响。annotation可以从源文件、class文件或者以在运行时反射的多种方式被读取。
当然annotation在某种程度上使javadoc tag更加完整。一般情况下,如果这个标记对java文档产生影响或者用于生成java文档的话,它应该作为一个javadoc tag;否则将作为一个annotation。

三、Annotation使用方法:

1。类型声明方式:
通常,应用程序并不是必须定义annotation类型,但是定义annotation类型并非难事。Annotation类型声明于一般的接口声明极为类似,区别只在于它在interface关键字前面使用“@”符号。
annotation 类型的每个方法声明定义了一个annotation类型成员,但方法声明不必有参数或者异常声明;方法返回值的类型被限制在以下的范围: primitives、String、Class、enums、annotation和前面类型的数组;方法可以有默认值。

下面是一个简单的annotation类型声明:
清单1:

    /**
     * Describes the Request-For-Enhancement(RFE) that led
     * to the presence of the annotated API element.
     */
    public @interface RequestForEnhancement {
        int    id();
        String synopsis();
        String engineer() default "[unassigned]";
        String date();    default "[unimplemented]";
    }

代码中只定义了一个annotation类型RequestForEnhancement。

2。修饰方法的annotation声明方式:
annotation 是一种修饰符,能够如其它修饰符(如public、static、final)一般使用。习惯用法是annotaions用在其它的修饰符前面。 annotations由“@+annotation类型+带有括号的成员-值列表”组成。这些成员的值必须是编译时常量(即在运行时不变)。

A:下面是一个使用了RequestForEnhancement annotation的方法声明:
清单2:

    @RequestForEnhancement(
        id       = 2868724,
        synopsis = "Enable time-travel",
        engineer = "Mr. Peabody",
        date     = "4/1/3007"
    )
    public static void travelThroughTime(Date destination) { ... }

B:当声明一个没有成员的annotation类型声明时,可使用以下方式:
清单3:

    /**
     * Indicates that the specification of the annotated API element
     * is preliminary and subject to change.
     */
    public @interface Preliminary { }

作为上面没有成员的annotation类型声明的简写方式:
清单4:

    @Preliminary public class TimeTravel { ... }

C:如果在annotations中只有唯一一个成员,则该成员应命名为value:
清单5:

    /**
     * Associates a copyright notice with the annotated API element.
     */
    public @interface Copyright {
        String value();
    }

更为方便的是对于具有唯一成员且成员名为value的annotation(如上文),在其使用时可以忽略掉成员名和赋值号(=):
清单6:

    @Copyright("2002 Yoyodyne Propulsion Systems")
    public class OscillationOverthruster { ... }

3。一个使用实例:
结合上面所讲的,我们在这里建立一个简单的基于annotation测试框架。首先我们需要一个annotation类型来表示某个方法是一个应该被测试工具运行的测试方法。
清单7:

    import java.lang.annotation.*;

    /**
     * Indicates that the annotated method is a test method.
     * This annotation should be used only on parameterless static methods.
     */
    @Retention(RetentionPolicy.RUNTIME)
    @Target(ElementType.METHOD)
    public @interface Test { }

值得注意的是annotaion类型声明是可以标注自己的,这样的annotation被称为“meta-annotations”。

在 上面的代码中,@Retention(RetentionPolicy.RUNTIME)这个meta-annotation表示了此类型的 annotation将被虚拟机保留使其能够在运行时通过反射被读取。而@Target(ElementType.METHOD)表示此类型的 annotation只能用于修饰方法声明。

下面是一个简单的程序,其中部分方法被上面的annotation所标注:
清单8:

    public class Foo {
        @Test public static void m1() { }
        public static void m2() { }
        @Test public static void m3() {
            throw new RuntimeException("Boom");
        }
        public static void m4() { }
        @Test public static void m5() { }
        public static void m6() { }
        @Test public static void m7() {
            throw new RuntimeException("Crash");
        }
        public static void m8() { }
    }

Here is the testing tool:

    import java.lang.reflect.*;

    public class RunTests {
       public static void main(String[] args) throws Exception {
          int passed = 0, failed = 0;
          for (Method m : Class.forName(args[0]).getMethods()) {
             if (m.isAnnotationPresent(Test.class)) {
                try {
                   m.invoke(null);
                   passed++;
                } catch (Throwable ex) {
                   System.out.printf("Test %s failed: %s %n", m, ex.getCause());
                   failed++;
                }
             }
          }
          System.out.printf("Passed: %d, Failed %d%n", passed, failed);
       }
    }

这 个程序从命令行参数中取出类名,并且遍历此类的所有方法,尝试调用其中被上面的测试annotation类型标注过的方法。在此过程中为了找出哪些方法被 annotation类型标注过,需要使用反射的方式执行此查询。如果在调用方法时抛出异常,此方法被认为已经失败,并打印一个失败报告。最后,打印运行 通过/失败的方法数量。
下面文字表示了如何运行这个基于annotation的测试工具:

清单9:

    $ java RunTests Foo
    Test public static void Foo.m3() failed: java.lang.RuntimeException: Boom
    Test public static void Foo.m7() failed: java.lang.RuntimeException: Crash
    Passed: 2, Failed 2

四、Annotation分类:

根据annotation的使用方法和用途主要分为以下几类:

1。内建Annotation——Java5.0版在java语法中经常用到的内建Annotation:
@Deprecated用于修饰已经过时的方法;
@Override用于修饰此方法覆盖了父类的方法(而非重载);
@SuppressWarnings用于通知java编译器禁止特定的编译警告。

下面代码展示了内建Annotation类型的用法:
清单10:

package com.bjinfotech.practice.annotation;

/**
 * 演示如何使用java5内建的annotation
 * 参考资料:
 * http://java.sun.com/docs/books/tutorial/java/javaOO/annotations.html
 * http://java.sun.com/j2se/1.5.0/docs/guide/language/annotations.html
 * http://mindprod.com/jgloss/annotations.html
 * @author cleverpig
 *
 */
import java.util.List;

public class UsingBuiltInAnnotation {
        //食物类
        class Food{}
        //干草类
        class Hay extends Food{}
        //动物类
        class Animal{
                Food getFood(){
                        return null;
                }
                //使用Annotation声明Deprecated方法
                @Deprecated
                void deprecatedMethod(){
                }
        }
        //马类-继承动物类
        class Horse extends Animal{
                //使用Annotation声明覆盖方法
                @Override
                Hay getFood(){
                        return new Hay();
                }
                //使用Annotation声明禁止警告
                @SuppressWarnings({"deprecation","unchecked"})
                void callDeprecatedMethod(List horseGroup){
                        Animal an=new Animal();
                        an.deprecatedMethod();
                        horseGroup.add(an);
                }
        }
}

2。开发者自定义Annotation:由开发者自定义Annotation类型。
下面是一个使用annotation进行方法测试的sample:

AnnotationDefineForTestFunction类型定义如下:
清单11:

package com.bjinfotech.practice.annotation;

import java.lang.annotation.*;
/**
 * 定义annotation
 * @author cleverpig
 *
 */
//加载在VM中,在运行时进行映射
@Retention(RetentionPolicy.RUNTIME)
//限定此annotation只能标示方法
@Target(ElementType.METHOD)
public @interface AnnotationDefineForTestFunction{}

测试annotation的代码如下:

清单12:

package com.bjinfotech.practice.annotation;

import java.lang.reflect.*;/**
 * 一个实例程序应用前面定义的Annotation:AnnotationDefineForTestFunction
 * @author cleverpig
 *
 */
public class UsingAnnotation {
        @AnnotationDefineForTestFunction public static void method01(){}

        public static void method02(){}

        @AnnotationDefineForTestFunction public static void method03(){
                throw new RuntimeException("method03");
        }

        public static void method04(){
                throw new RuntimeException("method04");
        }

        public static void main(String[] argv) throws Exception{
                int passed = 0, failed = 0;
                //被检测的类名
                String className="com.bjinfotech.practice.annotation.UsingAnnotation";
                //逐个检查此类的方法,当其方法使用annotation声明时调用此方法
            for (Method m : Class.forName(className).getMethods()) {
               if (m.isAnnotationPresent(AnnotationDefineForTestFunction.class)) {
                  try {
                     m.invoke(null);
                     passed++;
                  } catch (Throwable ex) {
                     System.out.printf("测试 %s 失败: %s %n", m, ex.getCause());
                     failed++;
                  }
               }
            }
            System.out.printf("测试结果: 通过: %d, 失败: %d%n", passed, failed);
        }
}

3。使用第三方开发的Annotation类型
这也是开发人员所常常用到的一种方式。比如我们在使用Hibernate3.0时就可以利用Annotation生成数据表映射配置文件,而不必使用Xdoclet。

五、总结:

1。 前面的文字说明了annotation的使用方法、定义方式、分类。初学者可以通过以上的说明制作简单的annotation程序,但是对于一些高级的 annotation应用(例如使用自定义annotation生成javabean映射xml文件)还需要进一步的研究和探讨。

2。同时,annotation运行存在两种方式:运行时、编译时。上文中讨论的都是在运行时的annotation应用,但在编译时的annotation应用还没有涉及,因为编译时的annotation要使用annotation processing tool。

涉及以上2方面的深入内容,作者将在后文《Java Annotation高级应用》中谈到。

六、参考资源:
·Matrix-Java开发者社区:http://www.matrix.org.cn
·http://java.sun.com/docs/books/tutorial/java/javaOO/annotations.html
·http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html
·http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html
·http://java.sun.com/j2se/1.5.0/docs/guide/apt/GettingStarted.html
·作者的Blog:http://blog.matrix.org.cn/page/cleverpig

Advertisements

Wildcard Type学习笔记

有三种关于wildcard的用法

  • ? extends Employee
  • ? super Manager
  • ?

一、测试背景

有一个泛型Pair<T>

package genericProgramming;

public class Pair<T> {
	public Pair(){
		first = null;
		second = null;
	}

	public Pair(T first, T second){
		this.first=first;
		this.second=second;
	}

	public T getFirst() {
		return first;
	}

	public void setFirst(T first) {
		this.first = first;
	}

	public T getSecond() {
		return second;
	}

	public void setSecond(T second) {
		this.second = second;
	}

	private T first;
	private T second;
}

两个有继承关系的类Employee和Manager,这里Manager extends Employee,Employee extends Object

package genericProgramming;

import java.util.*;

public class Employee {
	private String name;
	private double salary;
	private Date hireDay;

	public Employee(String n, double s, int year, int month, int day){
		name =n;
		salary =s;
		GregorianCalendar calendar = new GregorianCalendar(year, month-1, day);
		hireDay= calendar.getTime();
	}

	public String getName() {
		return name;
	}

	public double getSalary() {
		return salary;
	}

	public Date getHireDay() {
		return hireDay;
	}

	public void raiseSalary(double byPercent){
		double raise=salary * byPercent/100;
		salary+=raise;
	}
}
package genericProgramming;

public class Manager extends Employee {
	private double bonus;

	public Manager(String n, double s, int year, int month, int day){
		super(n,s,year,month,day);
		bonus=0;
	}

	public double getSalary(){
		double baseSalary=super.getSalary();
		return baseSalary+bonus;
	}

	public void setBonus(double b){
		bonus=b;
	}

	public double getBonus(){
		return bonus;
	}
}

二、关于三种wildcard的用法

关于 ? extends Employee :

  • 当如此定义时,调用时填入的必须是Employee本身或其子类,例如可以填入Employee,或者Manager,但是不能是Object。如下图所示:
  • Pair<? extends Employee>是Pair<Employee>和Pair<Manager>的super class
  • ? extends Employee getFirst() //合法
    void setFirst(? extends Employee) //不合法
    关于以上两行,更直观的是看使用过程中到底发生了什么

    先看看在get方法中发生了什么,如同 ? extends Employee getFirst() 定义的方法,如上图所示,显然是合法的,问题就是到底返回值究竟能赋给什么类型,实验的三种类型,Manager,Employee,Object,只有后两个能成功,所以,能接受 ? extends xxx 类型返回值的,是xxx以及其所有super class

    然后看看set方法中发生了什么,如上图所示,当尝试用 ? extends Employee 作为参数的类型时,编译器所认为的参数类型却是null,编译器无法确定究竟应该用什么类型去匹配参数,虽然看上去应该填入一个Employee的sub class。当然填入null是合法的,但是程序却无法正确进行下去了。
    实际上,从实际使用中考虑,这也是合理的。? extends Employee 是替代泛型<T>中的T的,显然在定义中,如果有两个变量a和b,他们都是T类型,那么a和b是可以相互赋值的,比如a=b,但是当T由? extends Employee替换之后,调用时,用来替换? extends Employee的可能是Employee的sub class A,或者B,将一个class A的变量和一个class B的变量相互赋值,显然是有问题的。
    所以,对于 ? extends xxx ,get方法可用,set方法不可用

关于 ? super Manager :

  • 当如此定义时,调用时填入的必须是Manager本身或其超类,例如可以填入Manager,Employee,Object,具体如下图:

  • Pair<? super Manager>是Pair<Manager>,Pair<Employee>和Pair<Object>的super class
  • ? super Manager getFirst()
    void setFirst(? super Manager)
    与上面的相反,? super Manager的缺陷是在get方法上,如下图:

    get方法虽然可以用,但是返回的类型是Object,之所以还能用的原因是Manager的super class是可数的,有终点的,于是那个终点Object就作为了返回类型,这样做是安全的。相比之下,满足? extends Employee的class数量是不确定的。
    关于set方法,如下图:

    这里很有趣,我曾以为能够填入的参数类型是Manager本身或其super class,然而实际上恰巧相反,对于set方法参数中的 ? super xxx,应该填入的类型是xxx本身或其sub class。仔细想一下,从起始的泛型到最后的调用,顺序应该是这样的:Pair<T>,Pair<? super Manager>,Pair<Manager>,Pair<Employee>或Pair<Object>,最后是setFirst(val),可见,val的类型必须同时满足使用? super Manager可能产生的所有情况,在这里,也就是Manager,Employee和Object,所以val的类型只能是Manager或其子类了

关于 ? :

  • Pair<?>似乎与Pair<T>很相像,但是Pair<?>继承了上述的诸多限制,而且是最坏的限制,比如get方法只能返回Object,set方法非法

三、泛型(generic)和通配符(wildcard)

我的理解是,泛型就像c里面的宏,用法像是直接无条件地将类型参数用给定的类名在源代码中替换掉,通配符的使用则是有条件地将类型参数用给定的类名在源代码中替换掉,然后再产生了一系列的使用限制(如上所说)

2011/07/11 通过JMX与Cassandra交互

1、首先去http://mx4j.sourceforge.net上下载3.0.1版本以上的MX4J库

2、解压后在lib文件夹下找到mx4j.jar和mx4j-tools.jar,拷贝到cassandra/lib下,重启cassandra

3、在jdk的bin目录中找到jconsole,启动,下面

3.1、如果是jconsole和cassandra都在一台机器上,那么在Local Process块中选择 org.apache.cassandra.thrift.CassandraDaemon

3.2、如果不在一台机器上,那么在Remote Process块中输入需要连接的<hostname>:<port>

——————————————–渣翻译来了————————————————————-

JMX:

JMX是一个Java API,通过两种方式提供了application的管理。一,JMX让你了解你的application的健康状况,和总体性能表现(例如memory,threads,和CPU usage),这些都是普遍适用于所有Java application的。二,JMX让你能够接触到你的application中(已经仪表化的application)的特定的方面。

所谓仪表化,就是指将application code包起来,以提供从application到JVM的hook,这使得JVM能够收集一些额外工具能够使用的数据。这些工具包括监视代理(monitoring agents),数据分析工具(data analysis tools),分析器(profilers)等。JMX不光能让你看到这些数据,还能在运行时更改application的值,以管理这些application(如果启动了这项功能)。

JMX所作的控制操作包括以下:

  • 低可用内存的检测,包括堆中每个刻度空间(graduation space)的大小
  • 进程信息,例如死锁检测,进程数量的峰值,以及当前活动进程数量。
  • 详细的类加载器 追踪
  • 日志级别控制
  • 应用的基本信息,例如application的运行时间,classpath等等

jconsole就是一个JMX代理,当然也有其他的JMX代理。

MBeans:

MBean,就是 managed bean,这是一个特殊的java bean类型,代表着JVM中一个可被管理的资源。MBeans与一个MBean server交互,以让他们的功能远程可用。