Skip to content

Latest commit

 

History

History
223 lines (160 loc) · 9.9 KB

README.md

File metadata and controls

223 lines (160 loc) · 9.9 KB
Raw

KlassIndex

GitHub Workflow Status (with branch) CodeFactor GitHub License GitHub last commit GitHub Release Date Maven Central

About

KlassIndex is the younger Kotlin brother of atteo/classindex. However, it differs from ClassIndex in various aspects.

Aspects ClassIndex KlassIndex
Language Java Kotlin
Supported Classes Any Java class Any Kotlin class
Supported Build Tools Maven and Gradle Gradle
Supported Scopes Annotations, Subclasses, Packages Annotations, Subclasses5
Service Loader Support Yes No, superfluous6
JaxB Index Yes No
Stores Documentation Yes No
Android Support Limited2 Yes
Runtime Performance Great Even Greater1
Filtering Support Limited Complete functional support3
Extension Support Yes Theoretically
Index external classes Yes, by extending the processor Yes, using kapt arguments
Jar Shading Support Yes Maybe
Compile Time Safety Limited4 Complete
Class Loader Required Yes No
License Apache 2.0 Apache 2.0

Explanation

  1. ClassIndex stores the qualified names of the classes to load at run time in the jar's resources. The resource parsing and class loading comes at a cost. In contrast, KlassIndex statically compiles the references. That means resource and classloading are not necessary. Excluded, however, are use cases where there are tons unreferenced of classes with only few of them to be loaded. ClassIndex might show a better performance then.
  2. ClassIndex depends on resource and class loading. In use cases in Android where no context is available or a different class loader is to be used, ClassIndex will fail. KlassIndex compiles the references statically to enable full support.
  3. KlassIndex provides all functional methods from Kotlin's Iterable, not just filters.
  4. ClassIndex uses workarounds to detect if classes are valid and still existent. KlassIndex, however, uses statically compiled generated classes so that the compiler can check their validity.
  5. Kotlin does not (yet?) have such a concept such as Java's package files. Thus, package indexing has been removed to be consistent with the Kotlin.
  6. The only use case in which a service loader is to be preferred over statical compilation is in plugin-based systems.

Methods

  • the list of classes annotated by a given annotation getAnnotated()
  • the list of classes implementing a given interface getSubclasses()

Advantages

KlassIndex

  • is faster than reading a file, it is not impacted by the usual performance penalty of the classpath scanning
  • does not depend on a class loader
  • is light-weight and simple
  • supports incremental compilation in IntelliJ and Android Studio

How to use it?

Add Dependency

Gradle

  • Add kapt
plugins {
    // Replace with the latest Kotlin version
    id "org.jetbrains.kotlin.kapt" version "1.+"
}
  • Add dependencies
// Replace with the latest versions from Jitpack
compile 'fyi.fax.klassindex:library:4.+'
kapt 'fyi.fax.klassindex:processor:4.+'
  • (Optional) Enable kapt build cache
kapt {
    useBuildCache = true
}

Gradle in Kotlin DSL

  • Add kapt
plugins {
    // Replace with the latest Kotlin version
    kotlin("kapt") version "1.+"
}
  • Add dependencies
// Replace with the latest versions from Jitpack
compile("fyi.fax.klassindex:library:4.+")
kapt("fyi.fax.klassindex:processor:4.+")
  • (Optional) Enable kapt build cache
kapt {
    useBuildCache = true
}

Annotations

  • Annotate your annotation with @IndexAnnotated
@IndexAnnotated
annotation class YourAnnotation
  • Retrieve a list of annotated classes at run-time
KlassIndex.getAnnotated(Component::class)

Subclasses

  • Annotate your superclass with @IndexSubclasses
@IndexSubclasses
interface YourSuperclass
  • Retrieve a list of annotated classes at run-time
KlassIndex.getSubclasses(YourSuperclass::class)

Index Traversing

Filtering allows you to select only classes with desired characteristics. Here are some basic samples:

  • Selecting only top-level classes
KlassIndex.getAnnotated(SomeAnnotation.class).topLevel()
  • Selecting only classes which are top level and public at the same time
KlassIndex.getAnnotated(SomeAnnotation.class).topLevel().withModifiers(Modifier.PUBLIC)
  • Selecting only the object instances from singleton classes that are annotated with an additional annotation.
KlassIndex.getAnnotated(SomeAnnotation.class).annotatedWith(SecondAnnotation::class).objects()

For more examples, check the test file.

Indexing Without Annotations

Sometimes, you cannot easily use annotations to trigger compile time indexing because you don't control the source code of the classes which should be annotated. For instance, you cannot add @IndexSubclasses meta-annotation to @Exception.

To add the regarding annotations to the desired external class, just add an argument to kapt.

kapt {
    arguments {
        arg(
                "fyi.fax.klassindex.IndexSubclasses", // IndexAnnotated alternatively
                "java.lang.Exception" // this is a vararg
        )
    }
}

Please consider that this option only provides you internal classes at the moment. That means, for the Exception example, you will only get your declared exceptions, not all available Java and Kotlin exceptions.

Make sure not to use Kotlin type aliases, they will not be recognized (e.g., not kotlin.Exception).

How the Magic Happens

Annotation Index Processor

KlassIndex indexes your classes at compile time by providing the implementation of the standard annotation processor. The index is then used by kapt utilizing kotlinpoet to generate new Kotlin source files that hold the static references to the indexed classes. The compiler uses the source files as if they were manually written.

Run Time Library

KlassIndex provides a library to access the statically compiled index from the generated classes and to process them.

Why KlassIndex

Speed

Traditional classpath scanning is a very slow process. Replacing it with compile-time indexing speeds Java applications bootstrap considerably.

Here are the results of the benchmark comparing ClassIndex with various scanning solutions.

Library Application startup time
None - hardcoded list 0:00.18
Scannotation 0:05.11
Reflections 0:05.37
Reflections Maven plugin 0:00.52
Corn 0:24.60
ClassIndex 0:00.18
KlassIndex TBD

Notes: benchmark was performed on Intel i5-2520M CPU @ 2.50GHz, classpath size was set to 121MB.