Skip to content

Commit

Permalink
markdown lint
Browse files Browse the repository at this point in the history
  • Loading branch information
matfax committed Oct 8, 2018
1 parent 29f4902 commit e9b1d47
Showing 1 changed file with 27 additions and 27 deletions.
54 changes: 27 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,64 +30,64 @@

### 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 with a cost. In contrast, **K**lassIndex statically compiles the references. That means resource and classloading are not necessary. Excluded, however, are use cases where you have tons of classes and want only to load few of them, ClassIndex might show a better performance.
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 with a cost. In contrast, **K**lassIndex statically compiles the references. That means resource and classloading are not necessary. Excluded, however, are use cases where you have tons of classes and want only to load few of them, ClassIndex might show a better performance.

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. **K**lassIndex compiles the references statically to enable full support.
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. **K**lassIndex compiles the references statically to enable full support.

3. New IntelliJ and Android Studio versions require newer versions of Gradle to provide full support.
3.New IntelliJ and Android Studio versions require newer versions of Gradle to provide full support.

4. **K**lassIndex provides all functional methods from Kotlin's `Iterable`, not just filters.
4.**K**lassIndex provides all functional methods from Kotlin's `Iterable`, not just filters.

5. ClassIndex uses workarounds to detect if classes are valid and still existent. **K**lassIndex, however uses statically compiled generated classes so that the compiler can check the validity.
5.ClassIndex uses workarounds to detect if classes are valid and still existent. **K**lassIndex, however uses statically compiled generated classes so that the compiler can check the validity.

6. 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.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.

7. ClassIndex does not provide separate dependency modules for annotation processing and compilation as required by newer Gradle versions (i.e., deprecated in Gradle 4.x, to be dropped in Gradle 5.x). **K**lassIndex provides a spearate annotation processor to be used with Gradle's `kotlin-kapt`.
7.ClassIndex does not provide separate dependency modules for annotation processing and compilation as required by newer Gradle versions (i.e., deprecated in Gradle 4.x, to be dropped in Gradle 5.x). **K**lassIndex provides a spearate annotation processor to be used with Gradle's `kotlin-kapt`.

8. The only use case in which a service loader is to be preferred over statical compilation are plugin-based systems.
8.The only use case in which a service loader is to be preferred over statical compilation are plugin-based systems.

### Methods

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

### Advantages
**K**lassIndex
- is faster than reading a file, it is not impacted by the usual performance penalty of the classpath scanning
- is not depending on a class loader
- is leight-weight and simple
- supports incremental compilation in IntelliJ and Android Studio
-is faster than reading a file, it is not impacted by the usual performance penalty of the classpath scanning
-is not depending on a class loader
-is leight-weight and simple
-supports incremental compilation in IntelliJ and Android Studio

## How to use it?

### Add Dependency
#### Gradle

* Add repository
-Add repository
```groovy
allprojects {
repositories {
maven { url 'https://jitpack.io' }
}
}
```
* Add dependencies
-Add dependencies
```groovy
compile 'com.github.matfax.klassindex:library:4.+'
kapt 'com.github.matfax.klassindex:processor:4.+'
```

#### Gradle in Kotlin DSL

* Add repository
-Add repository
```kotlin
allprojects {
repositories {
maven("https://jitpack.io")
}
}
```
* Add dependencies
-Add dependencies
```kotlin
compile("com.github.matfax.klassindex:library:4.+")
kapt("com.github.matfax.klassindex:processor:4.+")
Expand All @@ -98,24 +98,24 @@ For others, check: [Jitpack](https://jitpack.io/#matfax/klassindex)

### Annotations

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

### Subclasses

1. Annotate your superclass with @IndexSubclasses
1.Annotate your superclass with @IndexSubclasses
```kotlin
@IndexSubclasses
interface YourSuperclass
```
1. Retrieve a list of annotated classes at run-time
1.Retrieve a list of annotated classes at run-time
```kotlin
KlassIndex.getSubclasses(YourSuperclass::class)
```
Expand All @@ -124,19 +124,19 @@ KlassIndex.getSubclasses(YourSuperclass::class)

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

* Selecting only top-level classes
*Selecting only top-level classes

```kotlin
KlassIndex.getAnnotated(SomeAnnotation.class).topLevel()
```

* Selecting only classes which are top level and public at the same time
*Selecting only classes which are top level and public at the same time

```kotlin
KlassIndex.getAnnotated(SomeAnnotation.class).topLevel().withModifiers(Modifier.PUBLIC)
```

* Selecting only the object instances from singleton classes that are annotated with an additional annotation.
*Selecting only the object instances from singleton classes that are annotated with an additional annotation.

```kotlin
KlassIndex.getAnnotated(SomeAnnotation.class).annotatedWith(SecondAnnotation::class).objects()
Expand All @@ -148,7 +148,7 @@ For more examples, check the [test file](https://github.com/matfax/klassindex/bl

### Annotation Index Processor

**K**lassIndex indexes your classes at compile time by providing the implementation of the standard [annotation
**K**lassIndex indexes your classes at compile time by providing the implementation of the standard [annotation
processor](http://www.jcp.org/en/jsr/detail?id=269). 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
Expand All @@ -160,7 +160,7 @@ processor](http://www.jcp.org/en/jsr/detail?id=269). The index is then used by k
### Speed

Traditional classpath scanning is a [very](https://www.leveluplunch.com/blog/2015/08/11/reducing-startup-times-spring-applications-context/)
[slow](https://wiki.apache.org/tomcat/HowTo/FasterStartUp) process.
[slow](https://wiki.apache.org/tomcat/HowTo/FasterStartUp) process.
Replacing it with compile-time indexing speeds Java applications bootstrap considerably.

Here are the results of the [benchmark](https://github.com/atteo/classindex-benchmark) comparing ClassIndex with various scanning solutions.
Expand Down

0 comments on commit e9b1d47

Please sign in to comment.