documentation

Author: lehvolk

README.md

@@ -18,7 +18,39 @@ Information about classes, hierarchies, annotations, methods, fields, and their
 - [Full api reference](../../wiki/Api-reference)
 - [3-address bytecode representation](../../wiki/Three-address-instruction-list-IR)
 
-## Examples
+## Installation
+
+Gradle:
+```kotlin
+    implementation(group = "org.jacodb", name = "jacodb-api", version = "1.2.0")
+    implementation(group = "org.jacodb", name = "jacodb-core", version = "1.2.0")
+    implementation(group = "org.jacodb", name = "jacodb-analysis", version = "1.2.0")
+```
+
+or 
+
+Maven:
+```xml
+<dependencies>
+    <dependency>
+        <groupId>org.jacodb</groupId>
+        <artifactId>jacodb-core</artifactId>
+        <verison>1.2.0</verison>
+    </dependency>
+    <dependency>
+        <groupId>org.jacodb</groupId>
+        <artifactId>jacodb-api</artifactId>
+        <verison>1.2.0</verison>
+    </dependency>
+    <dependency>
+        <groupId>org.jacodb</groupId>
+        <artifactId>jacodb-analysis</artifactId>
+        <verison>1.2.0</verison>
+    </dependency>
+</dependencies>
+```
+
+## Concepts
 
 API has two levels: the one representing in filesystem (**bytecode** and **classes**) and the one appearing at runtime (**types**).
 
@@ -27,6 +59,26 @@ API has two levels: the one representing in filesystem (**bytecode** and **class
 
 Both levels are connected to `JcClasspath`. You can't modify **classes** retrieved from pure bytecode. **types** may be constructed manually by generics substitution.
 
+### Classes
+
+```java
+    public static void getStringFields() throws Exception {
+        JcDatabase database = JacoDB.async(new JcSettings().useProcessJavaRuntime()).get();
+        JcClassOrInterface clazz = database.asyncClasspath(emptyList()).get().findClassOrNull("java.lang.String");
+        System.out.println(clazz.getDeclaredFields());
+    }
+```
+
+Kotlin
+```kotlin
+    val database = jacodb {
+        useProcessJavaRuntime()
+    }
+    val clazz = database.classpath().findClassOrNull("java.lang.String")
+```
+
+More complex examples:
+
 Java
 ```java
 class Example {
@@ -55,14 +107,14 @@ class Example {
         System.out.println(JcClasses.getConstructors(jcClass).size());
 
         // At this point the database read the method bytecode and return the result.
-        return jcClass.getDeclaredMethods().get(0).body();
+        return jcClass.getDeclaredMethods().get(0).asmNode();
     }
 }
 ```
 
 Kotlin
 ```kotlin
-suspend fun findNormalDistribution(): Any {
+suspend fun findNormalDistribution(): MethodNode {
     val commonsMath32 = File("commons-math3-3.2.jar")
     val commonsMath36 = File("commons-math3-3.6.1.jar")
     val buildDir = File("my-project/build/classes/java/main")
@@ -86,13 +138,12 @@ suspend fun findNormalDistribution(): Any {
     println(jcClass.annotations.size)
 
     // At this point the database read the method bytecode and return the result.
-    return jcClass.methods[0].body()
+    return jcClass.methods[0].asmNode()
 }
 ```
 
-
-
-Note: the `body` method returns `null` if the to-be-processed JAR-file was changed or removed. Class could be in incomplete environment (i.e super class, interface, return type or parameter of method is not found in classpath) then api will throw `NoClassInClasspathException` at runtime. 
+Class could be in incomplete environment (i.e super class, interface, return type or parameter of method is not found in classpath) then api will throw `NoClassInClasspathException` at runtime. 
+To fix this install `UnknownClasses` feature into classpath during creation.
 
 The database can watch for file system changes in the background and refresh the JAR-files explicitly:
 
@@ -117,7 +168,6 @@ Kotlin
         watchFileSystem()
         useProcessJavaRuntime()
         loadByteCode(listOf(lib1, buildDir))
-        persistent("")
     }
 
     // A user rebuilds the buildDir folder.
@@ -171,6 +221,46 @@ Kotlin
     }
 ```
 
+## Features
+
+Features could be used for whole `JcDatabase` or particular `JcClasspath`
+
+### Usages
+
+Database feature for searching usages of fields and methods.
+
+```kotlin
+val database = jacodb {
+    install(Usages)
+}
+```
+
+see [more](https://jacodb.org/documentation/database-features/#usages)
+
+### Unknown Classes
+
+Mocks unknown classes. It's a grace way to handle incomplete classpaths
+
+```kotlin
+val database = jacodb {}
+val classpath = database.classpath(listOf(UnknownClasses))
+
+val clazz = classpath.findClass("UnknownClasses") // will return `JcClassOrInterface` instance
+```
+
+see [more](https://jacodb.org/documentation/classpath-features/#unknownClasses)
+
+
+### InMemory hierarchy
+
+A bit faster hierarchy but consume more RAM memory:
+
+```kotlin
+val database = jacodb {
+    install(InMemoryHierarchy)
+}
+```
+see [more](https://jacodb.org/documentation/database-features/#inmemoryhierarchy)
 
 ## Multithreading
 

jacodb-api/src/main/kotlin/org/jacodb/api/Classes.kt

@@ -48,6 +48,12 @@ interface JcClassOrInterface : JcAnnotatedSymbol, JcAccessible {
 
     fun <T> extensionValue(key: String): T?
 
+    /**
+     * lookup instance for this class. Use it to resolve field/method references from bytecode instructions
+     *
+     * It's not necessary that looked up method will return instance preserved in [JcClassOrInterface.declaredFields] or
+     * [JcClassOrInterface.declaredMethods] collections
+     */
     val lookup: JcLookup<JcField, JcMethod>
 
     val isAnnotation: Boolean

jacodb-api/src/main/kotlin/org/jacodb/api/JcLookup.kt

@@ -17,15 +17,52 @@
 package org.jacodb.api
 
 /**
- * lookup for fields and methods in [JcClassOrInterface] and [JcClassType]
+ * lookup for fields and methods in [JcClassOrInterface] and [JcClassType].
+ *
+ * It's not necessary that looked up method will return instance preserved in [JcClassOrInterface.declaredFields] or
+ * [JcClassOrInterface.declaredMethods] collections
  */
 @JvmDefaultWithoutCompatibility
 interface JcLookup<Field : JcAccessible, Method : JcAccessible> {
 
+    /**
+     * lookup for field with specific name
+     * @param name of field
+     */
     fun field(name: String): Field? = field(name, null)
+
+    /**
+     * lookup for field with specific name and expected type. Used during instructions parsing. In this case field type is preserved
+     * in Java bytecode
+     *
+     * @param name of field
+     * @param typeName expected type of field
+     */
     fun field(name: String, typeName: TypeName?): Field?
+
+    /**
+     * Lookup for method based on name and description:
+     * - in current class search for private methods too
+     * - in parent classes and interfaces search only for visible methods
+     *
+     * @param name method name
+     * @param description jvm description of method
+     */
     fun method(name: String, description: String): Method?
 
+    /**
+     * Lookup for static method based on name and description
+     *
+     * @param name method name
+     * @param description jvm description of method
+     */
     fun staticMethod(name: String, description: String): Method?
+
+    /**
+     * Lookup for methods placed in special instructions i.e `private` and `super` calls.
+     *
+     * @param name method name
+     * @param description jvm description of method
+     */
     fun specialMethod(name: String, description: String): Method?
 }

jacodb-api/src/main/kotlin/org/jacodb/api/Types.kt

@@ -101,6 +101,12 @@ interface JcClassType : JcRefType, JcAccessible {
 
     val innerTypes: List<JcClassType>
 
+    /**
+     * lookup instance for this class. Use it to resolve field/method references from bytecode instructions
+     *
+     * It's not necessary that looked up method will return instance preserved in [JcClassType.declaredFields] or
+     * [JcClassType.declaredMethods] collections
+     */
     val lookup: JcLookup<JcTypedField, JcTypedMethod>
 
 }

jacodb-core/src/main/kotlin/org/jacodb/impl/features/classpaths/JcUnknownClass.kt

@@ -92,6 +92,40 @@ class JcUnknownField(enclosingClass: JcUnknownClass, name: String, type: TypeNam
     }
 }
 
+/**
+ * Feature for mocking references to unknown classes. I.e let's assume that we have:
+ *
+ * ```
+ * class Bar {
+ *
+ *      int x = 0;
+ *
+ *      public void run() {
+ *          System.out.println("Hello world");
+ *      }
+ * }
+ *
+ * class Foo extends Bar {
+ *
+ *      Bar f = new Bar();
+ *
+ *      public void call() {
+ *          System.out.println(f.x);
+ *          run();
+ *      }
+ * }
+ * ```
+ *
+ * Let's assume that we have classpath that contains class `Foo` and doesn't contain `Bar`. Default behavior for
+ * classpath is to fail on trying to access class that doesn't exist. i.e parsing method instructions will fail, reading
+ * class hierarchy will fail, resolving method will fail.
+ *
+ * UnknownClasses feature fix this behaviour. All references pointing to nowhere will be resolved as special implementation
+ * of [JcClassOrInterface] instance. Such instance will have **empty** [JcClassOrInterface.declaredFields] and
+ * [JcClassOrInterface.declaredMethods] but all resolutions done through [JcClassOrInterface.lookup] interface will return
+ * mocked instances
+ *
+ */
 object UnknownClasses : JcClasspathExtFeature {
     override fun tryFindClass(classpath: JcClasspath, name: String): JcClasspathExtFeature.JcResolvedClassResult {
         return JcResolvedClassResultImpl(name, JcUnknownClass(classpath, name))

jacodb-examples/src/main/java/org/jacodb/examples/JavaReadMeExamples.java

@@ -16,11 +16,7 @@
 
 package org.jacodb.examples;
 
-import org.jacodb.api.JcClassOrInterface;
-import org.jacodb.api.JcClassType;
-import org.jacodb.api.JcClasspath;
-import org.jacodb.api.JcDatabase;
-import org.jacodb.api.JcType;
+import org.jacodb.api.*;
 import org.jacodb.api.ext.JcClasses;
 import org.jacodb.impl.JacoDB;
 import org.jacodb.impl.JcSettings;
@@ -29,6 +25,7 @@
 import java.io.File;
 import java.util.Arrays;
 
+import static java.util.Collections.emptyList;
 import static java.util.Collections.singletonList;
 
 public class JavaReadMeExamples {
@@ -40,6 +37,11 @@ public class JavaReadMeExamples {
     private static File lib2 = new File("2");
     private static File buildDir = new File("3");
 
+    public static void getStringFields() throws Exception {
+        JcDatabase database = JacoDB.async(new JcSettings().useProcessJavaRuntime()).get();
+        JcClassOrInterface clazz = database.asyncClasspath(emptyList()).get().findClassOrNull("java.lang.String");
+        System.out.println(clazz.getDeclaredFields());
+    }
 
     public static MethodNode findNormalDistribution() throws Exception {
         File commonsMath32 = new File("commons-math3-3.2.jar");