4

I am thinking about building an index (even a simple list stored in a file) of classes annotated with a certain annotation type at compile time with an annotation Processor in order to speed up annotated class retrieval at runtime.

So, is it a good practice? Are there any drawbacks? If it is as good as it seems to me now, why aren't there many libraries to do this in an easy way (the only one I have found is Class Index)? Instead for runtime processing there are so many?

kapex
  • 28,903
  • 6
  • 107
  • 121
Paolo Dragone
  • 939
  • 1
  • 11
  • 27
  • 1
    This sounds like [premature optimization](http://c2.com/cgi/wiki?PrematureOptimization) to me. Have you performed any benchmarks? – Elliott Frisch Jan 24 '15 at 19:25
  • ClassIndex did some interesting benchmark, I haven't done any myself. It can be premature optimization but the question remains. It is also an important design concern for my library I think. – Paolo Dragone Jan 24 '15 at 19:29
  • Quoting from your link *speeds Java **applications bootstrap** considerably*, how many times (typically) would you say your (or your users') application(s) typically bootstrap during a single run? Finally, the "Reflections Maven plugin" seems like it performs almost as well (on that single published benchmark)... – Elliott Frisch Jan 24 '15 at 19:32
  • Presumably runtime processing is more common because it's more useful & powerful. Compile-time processing only works for discovery of classes (or whatever) that are available at compile time. Imagine you're using annotations to make your library pluggable, or because your library provides annotations that end-users should be applying in their code (for example, Jackson). Compile-time annotation processing is not an option because such annotations are not present in code at the time _your_ library is compiled. – Matt Ball Jan 24 '15 at 19:35
  • 1
    @MattBall, isn't my processor run at compile time of the client's code if it is in `META-INF/services/javax.annotation.processing.Processor`?? – Paolo Dragone Jan 24 '15 at 19:38
  • @ElliottFrisch, maybe it is a silly point, but if it is faster to index at compile time, why not? – Paolo Dragone Jan 24 '15 at 19:46
  • Entirely depends on the client's build process. – Matt Ball Jan 24 '15 at 20:09
  • @MattBall, if I put `META-INF/services/javax.annotation.processing.Processor` in my library, the processor will be enabled unless the client will disable it on purpose, right? But if it disable it on purpose why should (s)he use my library anyway. – Paolo Dragone Jan 24 '15 at 20:16

3 Answers3

3

As an author of the ClassIndex library I can list several advantages of using annotation processing for annotation indexing, but also a drawbacks which I think hinder its widespread adoption.

Advantages:

  • Indexing using annotation processing is based on the official JSR 269. On the other hand the classpath scanning relies on Java internals. It is a common knowledge that ClassLoaders do not have an API to retrieve a list of annotated classes. But what is more surprising is that the generic ClassLoader does not allow to list folders and JAR files from where it tries to load the classes. Classpath scanners assume the only classloader used to load classes is URLClassLoader which allows to retrieve source URLs for scanning using getURLs() method.
  • There are environments where usual classpath scanners do not work, that is the case on Android where Dalvik Executable format is used.
  • Constant run-time complexity makes compile-time indexing super fast.
  • Project Jigsaw plans to bring annotation detection to Java. Current requirements also suggest a compile-time indexing as a viable implementation for it. It even introduces @Indexed meta-annotation with the same purpose as @IndexAnnotated in ClassIndex library.

Drawbacks:

  • JSR 269 is poorly supported across Java compilers and tools. There were several bugs in the earlier javac versions. Eclipse's custom JDT compiler has even more bugs and it does not support automatic discovery of annotation processors. ClassIndex includes workarounds for many of those issues.
  • Classpath scanning is the facto standard and is very well supported.
  • Application boot time is rarely a bottleneck to worry about.
Sławek
  • 1,450
  • 14
  • 14
2

A sub-project of JBoss WildFly, may be interesting to you: Jandex.

It creates annotation indexes at build time (and index file can be added to the JAR) or runtime (annotations are retrieved by examining class files, not through reflection), significantly increasing performance of annotation retrieval as it avoids the need to actually load classes.

Jandex sounds pretty much like what you are after.

Gunnar
  • 18,095
  • 1
  • 53
  • 73
1

I think the main disadvantages is that it's more complicated. Annotation processing is a whole new API and concept that many developers aren't familiar with. The Reflection API is easier and more well known. You can usually accomplish the same tasks at runtime.

If better startup performance is crucial (which is rarely the case) then maybe it's worth the added complexity.

I wouldn't trust the benchmarks though. They state "classpath size was set to 121MB" - an arbitrary value that makes any comparison to hard coded or compile time processing completely useless. Why would you want to scan the whole class path anyway? Scanning only the developers classes would be more reasonable in most cases.

Many frameworks use configuration files or have an API to limit the classes or packages that need to be scanned. This increases startup time significantly.

why aren't there many libraries to do this

Many OSGi tools/frameworks do this. Annotations are scanned at compile time and meta-data is written to the jar manifest file or they create more sophisticated meta-data files. I suspect the main reason for this is to keep compatibility with bnd and similar tools, which have been used to built and compile time analysis of OSGi components before annotations or annotation processing got more popular. Also, OSGi component have their own lifecycle and can come and go at any time. So this is a case where startup time does matter a bit more, as you can't only scan once at application start. You would need to scan for annotations whenever a component (re-)starts.

I wouldn't say it's a good nor bad practice. Use this technique when it fits your needs. I would avoid adding to much complexity for the sake of a few milliseconds startup time.

kapex
  • 28,903
  • 6
  • 107
  • 121
  • Thanks for the conspicuous answer, really helpful to get a wider view. Thinking about it I've actually found a downside of compile time indexing which is the lack of the applicability to pluggable libraries such as implementations of abstract factories and SPI. I am not sure if I should put this in an answer to my own question. – Paolo Dragone Jan 25 '15 at 13:41