org.atmosphere.util.annotation

Class AnnotationDetector

java.lang.Object

org.atmosphere.util.annotation.AnnotationDetector

public final class AnnotationDetector
extends Object

AnnotationDetector reads Java Class File (".class") files and reports the encountered annotations via a simple, developer friendly API.
Main advantages of this library compared with similar solutions are:

• light weight (no dependencies, simple API, 15 kb jar file)
• very fast (fastest annotation detection library as far as i know)

A Java Class File consists of a stream of 8-bit bytes. All 16-bit, 32-bit, and 64-bit quantities are constructed by reading in two, four, and eight consecutive 8-bit bytes, respectively. Multi byte data items are always stored in big-endian order, where the high bytes come first. In the Java and Java 2 platforms, this format is supported by interfaces DataInput and DataOutput.
A class file consists of a single ClassFile structure:

 ClassFile {
   u4 magic;
   u2 minor_version;
   u2 major_version;
   u2 constant_pool_count;
   cp_info constant_pool[constant_pool_count-1];
   u2 access_flags;
   u2 this_class;
   u2 super_class;
   u2 interfaces_count;
   u2 interfaces[interfaces_count];
   u2 fields_count;
   field_info fields[fields_count];
   u2 methods_count;
   method_info methods[methods_count];
   u2 attributes_count;
   attribute_info attributes[attributes_count];
 }

 Where:
 u1 unsigned byte DataInput.readUnsignedByte()
 u2 unsigned short DataInput.readUnsignedShort()
 u4 unsigned int DataInput.readInt()

 Annotations are stored as Attributes (i.e. "RuntimeVisibleAnnotations" and
 "RuntimeInvisibleAnnotations").
 

References:

• Java class file (Wikipedia) (Gentle Introduction);
• Class File Format Specification (Java 6 version) and the Java VM Specification (Chapter 4) for the real work.
• scanning java annotations at runtime.

Similar projects / libraries:

• JBoss MC Scanning lib;
• Google Reflections, in fact an improved version of scannotation;
• annovention, improved version of the original Annovention project. Available from maven: tv.cntt:annovention:1.2;
• If using the Spring Framework, this is the way to go.

All above mentioned projects make use of a byte code manipulation library (like BCEL, ASM or Javassist).

Since:

annotation-detector 3.0.0

Author:

Ronald K. Muller

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	AnnotationDetector.FieldReporter
static interface	AnnotationDetector.MethodReporter
static interface	AnnotationDetector.Reporter Reporter is the base interface, used to report the detected annotations.
static interface	AnnotationDetector.TypeReporter

Constructor Summary

Constructors

Constructor and Description
AnnotationDetector(AnnotationDetector.Reporter reporter) Create a new AnnotationDetector, reporting the detected annotations to the specified Reporter.

Method Summary

Methods

Modifier and Type	Method and Description
void	destroy() Reclaim memory.
void	detect() Report all Java ClassFile files available on the class path.
void	detect(File... filesOrDirectories) Report all Java ClassFile files available available from the specified files and/or directories, including sub directories.
void	detect(String... packageNames) Report all Java ClassFile files available available on the class path from the specified packages and sub packages.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AnnotationDetector

public AnnotationDetector(AnnotationDetector.Reporter reporter)

Create a new AnnotationDetector, reporting the detected annotations to the specified Reporter.

Method Detail

detect

public final void detect()
                  throws IOException

Report all Java ClassFile files available on the class path.

Throws:

IOException

See Also:

detect(java.io.File...)

detect

public final void detect(String... packageNames)
                  throws IOException

Report all Java ClassFile files available available on the class path from the specified packages and sub packages.

Throws:

IOException

See Also:

detect(java.io.File...)

detect

public final void detect(File... filesOrDirectories)
                  throws IOException

Report all Java ClassFile files available available from the specified files and/or directories, including sub directories.
Note that non-class files (files, not starting with the magic number CAFEBABE are silently ignored.

Throws:

IOException

destroy

public void destroy()

Reclaim memory.