Added readme
This commit is contained in:
nathan
parent
20913ad79c
commit
086b89a438
154
README.md
Normal file
154
README.md
Normal file
|
|
@ -0,0 +1,154 @@
|
|||
Annotations
|
||||
===========
|
||||
|
||||
|
||||
The Annotations project is based on, and *almost* identical to the excellent [infomas AnnotationDetector](https://github.com/rmuller/infomas-asl).
|
||||
There were **major** changes to the API to provide for a way to easily extend the scanning functionality, hence it lives on it's own.
|
||||
|
||||
|
||||
The main features of this annotations scanning library:
|
||||
- scans the bytecode for annotation information, meaning classes do not have to be loaded by the JVM
|
||||
- small footprint
|
||||
- *extremely fast* performance
|
||||
- can scan the classpath, classloader, or specified location
|
||||
- uses the SLF4j logging interface
|
||||
|
||||
- This is for cross-platform use, specifically - linux 32/64, mac 32/64, and windows 32/64. Java 6+
|
||||
|
||||
|
||||
|
||||
Included is the README from the infomas-asl project, for ease of understanding functionality.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
# infomas-asl
|
||||
|
||||
[](http://travis-ci.org/rmuller/infomas-asl)
|
||||
|
||||
INFOMAS ASL contains all open sourced code from the INFOMAS PCM Application Suite. All code is licensed by the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0), so it can be used by both open source and commercial projects.
|
||||
|
||||
The INFOMAS PCM Application Suite is a commercial Product Content Management (also known as PIM, Product Information Management) Application. For more information, visit http://www.xiam.nl.
|
||||
|
||||
## Warning: API Change!!
|
||||
Starting version 3.1.0-SNAPSHOT the API has been changed considerably and several new features
|
||||
have been added. Do not worry, we did not sacrifice the unique selling points of this library:
|
||||
simple API, small footprint and great performance. Performance is even improved by about 10%!
|
||||
The library size increased from 16 kB to 20 kB.
|
||||
This version is not (yet) released to Maven Central, so if you disagree with some changes or
|
||||
have better ideas, please let us know!
|
||||
|
||||
See (git) branche "release 3.1".
|
||||
|
||||
Changes (3.1.0-SNAPSHOT):
|
||||
+ More fluent API, builder style
|
||||
+ Made API Java 8 friendly (using Functional interfaces / SAM's)
|
||||
+ Added standard logging (using standard `java.util.logging`), removed DEBUG logging
|
||||
+ Some efficiency improvements
|
||||
+ Simplified API for standard use cases (see issue #7)
|
||||
+ Added possibility to filter scanned classes based on the file name (see issue #11)
|
||||
+ Possibility to report types, fields, methods and annotations as `java.lang.Class`, `java.lang.reflect.Field`, `java.lang.reflect.Method` and `java.lang.annotation.Annotation` (see issue #6)
|
||||
|
||||
## Quick Facts
|
||||
+ Simple builder style API
|
||||
+ Very fast (on moderate hardware about 200 MB/s)!
|
||||
+ Lightweight, no dependencies, only 20 kb jar
|
||||
+ Language: Java 6 SE or better with Java 8 friendly API
|
||||
+ Tested with Oracle JDK 6, 7, 8 and OpenJDK 6 and 7 (Last four VM's using
|
||||
[Travis CI Server](https://travis-ci.org/))
|
||||
+ OSGi Bundle artifact
|
||||
+ Apache License, Version 2.0
|
||||
+ Build System: Maven 3
|
||||
+ Maven Artifacts are available from [Central Maven](http://search.maven.org/#search%7Cga%7C1%7Cinfomas)
|
||||
+ [Project information generated by Maven](http://rmuller.github.io/infomas-asl/)
|
||||
|
||||
## Modules
|
||||
Currently INFOMAS ASL contains the following modules:
|
||||
|
||||
+ annotation-detector
|
||||
+ More to come ...
|
||||
|
||||
### annotation-detector
|
||||
This library can be used to scan (part of) the class path for annotated classes, methods or
|
||||
instance variables.
|
||||
Main advantages of this library compared with similar solutions are: light weight
|
||||
(**no dependencies**, simple API, **20 kb jar file**) and **very fast**
|
||||
(fastest annotation detection library as far as I know).
|
||||
|
||||
#### Maven configuration:
|
||||
|
||||
``` xml
|
||||
<dependency>
|
||||
<groupId>eu.infomas</groupId>
|
||||
<artifactId>annotation-detector</artifactId>
|
||||
<version>3.0.4</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
#### Example Usage (3.0.x versions):
|
||||
Put the `annotation-detector-3.0.x.jar` on the class path. No other dependencies are required!
|
||||
You can either scan the complete class path or only scan specified packages or Files
|
||||
(see [JavaDoc](http://rmuller.github.io/infomas-asl/annotation-detector/apidocs/index.html)
|
||||
for more details).
|
||||
|
||||
``` java
|
||||
// Scan all .class files on the class path
|
||||
// Report all .class files, with org.junit.Test annotated methods
|
||||
final MethodReporter reporter = new MethodReporter() {
|
||||
|
||||
@SuppressWarnings("unchecked")
|
||||
@Override
|
||||
public Class<? extends Annotation>[] annotations() {
|
||||
return new Class[]{Test.class};
|
||||
}
|
||||
|
||||
@Override
|
||||
public void reportMethodAnnotation(Class<? extends Annotation> annotation,
|
||||
String className, String methodName) {
|
||||
// do something
|
||||
}
|
||||
|
||||
};
|
||||
final AnnotationDetector cf = new AnnotationDetector(reporter);
|
||||
cf.detect();
|
||||
```
|
||||
|
||||
That's all!
|
||||
|
||||
#### Example Usage (3.1.x versions):
|
||||
Put the `annotation-detector-3.1.x.jar` on the class path. No other dependencies are required!
|
||||
You can either scan the complete class path or only scan specified packages or Files
|
||||
(see [JavaDoc](http://rmuller.github.io/infomas-asl/annotation-detector/apidocs/index.html)
|
||||
for more details).
|
||||
|
||||
``` java
|
||||
// Get a List with all classes annotated with @RuntimeVisibleTestAnnotation (Java 8 syntax)
|
||||
List<Class<?>> types = AnnotationDetector.scanClassPath()
|
||||
.forAnnotations(RuntimeVisibleTestAnnotation.class)
|
||||
.collect(AnnotationDetector::getType);
|
||||
|
||||
assertEquals(1, types.size());
|
||||
assertSame(NewApiTest.class, types.get(0));
|
||||
|
||||
// Get a List with all methods annotated with @RuntimeVisibleTestAnnotation, excluding
|
||||
// files ending with "Test.class" in the "eu.infomas" package and subpackages (Java 8 syntax)
|
||||
List<Method> methods = AnnotationDetector.scanClassPath("eu.infomas") // or: scanFiles(File... files)
|
||||
.forAnnotations(RuntimeVisibleTestAnnotation.class) // one or more annotations
|
||||
.on(ElementType.METHOD) // optional, default ElementType.TYPE. One ore more element types
|
||||
.filter((File dir, String name) -> !name.endsWith("Test.class")) // optional, default all *.class files
|
||||
.collect(AnnotationDetector::getMethod);
|
||||
|
||||
assertEquals(1, methods.size());
|
||||
assertEquals(void.class, methods.get(0).getReturnType());
|
||||
```
|
||||
|
||||
Even simpler, isn't it?
|
||||
|
||||
## License
|
||||
|
||||
Copyright (c) 2011 - 2014 XIAM Solutions B.V.
|
||||
|
||||
Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
[](https://www.ohloh.net/accounts/224392?ref=Tiny)
|
||||
Loading…
Reference in New Issue
Block a user