#37 javadoc: enterprise, commons, lambda

assira.commons/src/main/java/net/ranides/assira/io/uri/impl/CDataHandler.java

@@ -65,10 +65,17 @@ public class CDataHandler implements URIHandler {
 
     private final URIResolver resolver;
 
+    /**
+     * Default constructor
+     */
     public CDataHandler() {
         this.resolver = URIResolver.DEFAULT;
     }
 
+    /**
+     * Constructor used by ServiceLoader inside static initialization of {@link URIResolver}
+     * @param resolver owner
+     */
     public CDataHandler(URIResolver resolver) {
         this.resolver = resolver;
     }
@@ -78,6 +85,15 @@ public class CDataHandler implements URIHandler {
         return new CDataHandle(uri);
     }
 
+    /**
+     * Helper method, tries to resolve URI given in string
+     *
+     * @param uri uri
+     * @return CDataHandle
+     *
+     * @throws IOException if cdata section is invalid
+     * @throws URISyntaxException if URI is invalid
+     */
     public URIHandle resolve(String uri) throws IOException, URISyntaxException {
         return new CDataHandle(new URI(uri));
     }

assira.commons/src/main/java/net/ranides/assira/io/uri/impl/CFTPHandler.java

@@ -52,12 +52,19 @@ public class CFTPHandler implements URIHandler {
     private final URIResolver resolver;
     
     private final FTPManager man = new FTPManager();
-        
-    
+
+
+    /**
+     * Default constructor
+     */
     public CFTPHandler() {
         this.resolver = URIResolver.DEFAULT;
     }
 
+    /**
+     * Constructor used by ServiceLoader inside static initialization of {@link URIResolver}
+     * @param resolver owner
+     */
     public CFTPHandler(URIResolver resolver) {
         this.resolver = resolver;
     }

assira.commons/src/main/java/net/ranides/assira/io/uri/impl/CHTTPHandler.java

@@ -53,11 +53,18 @@ public class CHTTPHandler implements URIHandler {
     private static final Pattern RE_CHARSET = Pattern.compile(";[ ]*charset=([^; ]+)");
 
     private final URIResolver resolver;
-    
+
+    /**
+     * Default constructor
+     */
     public CHTTPHandler() {
         this.resolver = URIResolver.DEFAULT;
     }
 
+    /**
+     * Constructor used by ServiceLoader inside static initialization of {@link URIResolver}
+     * @param resolver owner
+     */
     public CHTTPHandler(URIResolver resolver) {
         this.resolver = resolver;
     }

assira.enterprise/src/main/java/net/ranides/assira/ee/CacheMapCleaner.java

@@ -7,12 +7,19 @@ import javax.annotation.PreDestroy;
 import javax.ejb.Singleton;
 import javax.ejb.Startup;
 
+/**
+ * Singleton which starts automatically as deamon thread and cleans CacheMap in the background.
+ * Cleaning cache in the background is a bit better than cleaning just at the moment when user reads from cache.
+ */
 @Singleton
 @Startup
 public class CacheMapCleaner {
 
     private Thread thread;
 
+    /**
+     * Starts deamon thread. Called automatically by Java EE container at application startup.
+     */
     @PostConstruct
     public void init() {
         thread = new Thread(() -> CacheMap.cleanup(true), "assira.ee cache cleanup");
@@ -20,6 +27,9 @@ public class CacheMapCleaner {
         thread.start();
     }
 
+    /**
+     * Stops deamon thread. Called automatically by Java EE container at application shutdown.
+     */
     @PreDestroy
     public void destroy() {
         thread.interrupt();

assira.junit/src/main/java/net/ranides/assira/junit/TestUtils.java

@@ -18,6 +18,8 @@ import java.util.function.Supplier;
 import java.util.regex.Pattern;
 
 /**
+ * Basic support methods used by junit implementation.
+ * This class is package accesible and shouldn't be used by client code.
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */
@@ -28,6 +30,13 @@ final class TestUtils {
 		/* utility class */
 	}
 
+    /**
+     * Creates new instance of the same type as provided.
+     * It does not copy state!
+     *
+     * @param object object
+     * @return new object
+     */
 	public static Object copy(Object object) {
 		try {
 			return object.getClass().newInstance();
@@ -35,7 +44,13 @@ final class TestUtils {
 			return rethrow(cause);
 		}
 	}
-	
+
+    /**
+     * Returns type of result produced by specified method.
+     *
+     * @param method method
+     * @return result type
+     */
 	public static Class<?> typeof(Method method) {
         Class<?> cparam = method.getParameterTypes()[0];
         if(Supplier.class.isAssignableFrom(cparam)) {
@@ -115,7 +130,10 @@ final class TestUtils {
 		}
 		return ret;
 	}
-	
+
+    /**
+     * Wrapper, workaround for immutable int type in java.
+     */
 	public static final class ICounter {
 		
         private int value = 0;
@@ -128,7 +146,10 @@ final class TestUtils {
 			return value;
 		}
     }
-	
+
+    /**
+     * Wrapper for list: used by TestContractRunner to store all patterns for ignored methods.
+     */
 	public static final class IPatterns {
 		
 		private final List<Pattern> patterns = new ArrayList<>();
@@ -156,7 +177,11 @@ final class TestUtils {
 			return patterns.stream().anyMatch(p -> p.matcher(value).matches());
 		}
 	}
-	
+
+    /**
+     * Wrapper for some field inside specific object.
+     * Allow to read and write to specific field of binded object.
+     */
 	public static final class IField {
 		
         private final Object object;

assira.lambda/src/main/java/net/ranides/assira/reflection/CPInspector.java

@@ -16,18 +16,33 @@ import java.util.function.IntFunction;
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 
+/**
+ * Non-portable class for accessing JVM constant pool.
+ *
+ * We use {@code jdk.internal.reflect.ConstantPool.ConstantPool}
+ * retrieved by native method {@code Class#getConstantPool()}
+ * Retrieved object is converted to interface-compatible form using AdapterFactory.
+ */
 @UtilityClass
 public class CPInspector {
 
+    /**
+     * Returns constant pool for specified class
+     * It returns well-defined interface, hiding the fact, that different JVM versions can return different objects.
+     *
+     * @param type class to inspect
+     * @return constant pool accessor
+     */
     @Meta.UnstableAPI
     public static ConstantAdapter11 getConstantPool(Class<?> type) {
         return AdapterFactory.getSystem().cast(Li.ADAPTER, MethodUtils.$invoke(Li.GET_CONSTANT_POOL, type));
     }
 
     /**
+     * Inspects constant pool to return all methods referenced inside class
      *
-     * @param clazz
-     * @return all methods referenced in class' bytecode
+     * @param clazz clazz
+     * @return methods
      */
     @Meta.UnstableAPI
     public static Stream<Method> getMethods(Class<?> clazz) {
@@ -37,6 +52,13 @@ public class CPInspector {
             .map(m -> (Method)m);
     }
 
+    /**
+     * Inspects constant pool to return all constructors of given class
+     *
+     * @param clazz clazz
+     * @param <T> clazz
+     * @return constructors
+     */
     @SuppressWarnings("unchecked")
     @Meta.UnstableAPI
     public static <T> Stream<Constructor<T>> getConstructors(Class<T> clazz) {
@@ -47,9 +69,10 @@ public class CPInspector {
     }
 
     /**
+     * Inspects constant pool to return all fields referenced in given class
      *
-     * @param clazz
-     * @return fields referenced in class' bytecode
+     * @param clazz clazz
+     * @return fields
      */
     @Meta.UnstableAPI
     public static Stream<Field> getFields(Class<?> clazz) {
@@ -58,9 +81,10 @@ public class CPInspector {
     }
 
     /**
+     * Inspects constant pool to return all types referenced in given class
      *
-     * @param clazz
-     * @return types referenced in class' bytecode
+     * @param clazz clazz
+     * @return types
      */
     @Meta.UnstableAPI
     public static Stream<Class<?>> getClasses(Class<?> clazz) {
@@ -69,9 +93,10 @@ public class CPInspector {
     }
 
     /**
+     * Inspects constant pool to return all string constants referenced in given class
      *
-     * @param clazz
-     * @return string constants referenced in class' bytecode
+     * @param clazz clazz
+     * @return string constants
      */
     @Meta.UnstableAPI
     public static Stream<String> getStrings(Class<?> clazz) {
@@ -79,6 +104,11 @@ public class CPInspector {
         return StreamSupport.stream(new CPSpliterator<>(cp.getSize(), cp::getUTF8At), false);
     }
 
+    /**
+     * ConstanPool interface defined in JDK8.
+     * See: jdk.internal.reflect.ConstantPool
+     */
+    @SuppressWarnings("MissingJavadoc")
     public interface ConstantAdapter {
 
         int getSize();
@@ -111,6 +141,11 @@ public class CPInspector {
 
     }
 
+    /**
+     * ConstanPool interface defined in JDK11.
+     * See: jdk.internal.reflect.ConstantPool
+     */
+    @SuppressWarnings("MissingJavadoc")
     public interface ConstantAdapter11 extends ConstantAdapter {
         int getClassRefIndexAt(int index);
 

assira.lambda/src/main/java/net/ranides/assira/reflection/LambdaReflect.java

@@ -1,8 +1,13 @@
 package net.ranides.assira.reflection;
 
+import lombok.experimental.UtilityClass;
 import net.ranides.assira.annotations.Meta;
 import net.ranides.assira.reflection.impl.LMethodFactory;
 
+/**
+ * Utility class for inspecting lambda expressions.
+ */
+@UtilityClass
 public class LambdaReflect {
 
     /**

assira.lambda/src/main/java/net/ranides/assira/reflection/UnsafeUtils.java

@@ -1,12 +1,26 @@
 package net.ranides.assira.reflection;
 
+import lombok.experimental.UtilityClass;
 import net.ranides.assira.annotations.Meta;
 
 import java.lang.reflect.Field;
 import java.security.ProtectionDomain;
 
+/**
+ * Utility class giving access to sun.misc.Unsafe
+ * It is not portable across JVM versions.
+ *
+ * It supports more than one version of JVM, and tries to bypass all JVM protection
+ * but should be used very carefully, because any JVM (including minor revision) can be incompatible.
+ */
+@UtilityClass
 public class UnsafeUtils {
 
+    /**
+     * Most recent versions of JVM (starting from 11) prints warnings about unsafe reflective operations.
+     * We can try to suppress it.
+     * There is no guarantee that this method will work, but we will try to do best, to not crash.
+     */
     public static void suppressReflectionWarning() {
         try {
             var cls = Class.forName("jdk.internal.module.IllegalAccessLogger");
@@ -19,16 +33,34 @@ public class UnsafeUtils {
         }
     }
 
+    /**
+     * Returns sun.misc.Unsafe object which should supported by every JVM (including as old versions as Java 6)
+     *
+     * @return sun.misc.Unsafe
+     * @throws ReflectiveOperationException internal error
+     */
     @Meta.UnstableAPI
     public static UnsafeAdapter getUnsafe() throws ReflectiveOperationException {
         return getUnsafe0(UnsafeAdapter.class);
     }
 
+    /**
+     * Returns sun.misc.Unsafe object which should supported by JVM 8+
+     *
+     * @return sun.misc.Unsafe
+     * @throws ReflectiveOperationException internal error
+     */
     @Meta.UnstableAPI
     public static UnsafeAdapter8 getUnsafe8() throws ReflectiveOperationException {
         return getUnsafe0(UnsafeAdapter8.class);
     }
 
+    /**
+     * Returns sun.misc.Unsafe object which should supported by JVM 9+
+     *
+     * @return sun.misc.Unsafe
+     * @throws ReflectiveOperationException internal error
+     */
     @Meta.UnstableAPI
     public static UnsafeAdapter9 getUnsafe9() throws ReflectiveOperationException {
         return getUnsafe0(UnsafeAdapter9.class);

assira.lambda/src/main/java/net/ranides/assira/reflection/impl/LMethod.java

@@ -20,6 +20,9 @@ import net.ranides.assira.reflection.util.ReflectUtils;
 import static net.ranides.assira.reflection.IAttribute.*;
 
 /**
+ * IMethod representing lambda expression.
+ *
+ * Please note, that implementation uses {@link CPInspector} which is not portable.
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */

assira.lambda/src/main/java/net/ranides/assira/reflection/impl/LMethodFactory.java

@@ -9,14 +9,18 @@ import java.util.List;
 
 import static net.ranides.assira.reflection.IAttribute.*;
 
+/**
+ * Static factory for lambda methods.
+ * Caches results internally using lambda object as cache key.
+ */
 public class LMethodFactory {
 
     private static final CacheMap<Object, IMethod> FUNCTIONS = CacheMap.getInstance(LMethodFactory::inewFunction);
 
     /**
-     * Collect information for lambda expression
-     * @param object
-     * @return
+     * Collects information for given lambda expression
+     * @param object object
+     * @return IMethod
      */
     public static IMethod typeinfo(Object object) {
         return FUNCTIONS.get(object);