#37 javadoc: reflection

assira.core/src/main/java/net/ranides/assira/collection/query/CQuery.java

@@ -460,8 +460,24 @@ public interface CQuery<T> extends Iterable<T> {
      */
     <R> CQuery<R> map(Function<? super T,R> f);
 
+    /**
+     * Returns query which casts every item to specified class.
+     * Please note: supports partial evaluation.
+     *
+     * @param f f
+     * @return query
+     * @param <R> R
+     */
     <R> CQuery<R> map(Class<R> f);
 
+    /**
+     * Returns query which casts every item to specified class.
+     * Please note: supports partial evaluation.
+     *
+     * @param f f
+     * @return query
+     * @param <R> R
+     */
     <R> CQuery<R> map(IClass<R> f);
 
     /**

assira.core/src/main/java/net/ranides/assira/events/ActiveEvent.java

@@ -1,109 +0,0 @@
-package net.ranides.assira.events;
-
-
-import java.util.concurrent.atomic.AtomicBoolean;
-
-/**
- * It is quite specific base class for events, which can be observed for completion.
- *
- * When you create ActiveEvent, you can pass it into any dispatcher and wait using #await method.
- * This method will block as long as event will be processed by some ActiveEventListener.
- *
- * You can cancel event at any time, and then ActiveEventListener will ignore it.
- *
- * Please note, that this event must be sent to dispatcher implementing ActiveEventListener
- * interface. If not, then the whole functionality won't work.
- */
-public class ActiveEvent implements Event {
-
-    private final Object lock = new Object();
-
-    private int counter = 0;
-
-    private final AtomicBoolean canceled = new AtomicBoolean(false);
-
-    /**
-     * Creates new event
-     */
-    protected ActiveEvent() {
-        // do nothing
-    }
-
-    /**
-     * Cancel this event. ActiveEventListeners ignore canceled events.
-     *
-     * @return true
-     */
-    public boolean cancel() {
-        return canceled.compareAndSet(false, true);
-    }
-
-    @Override
-    public void dispatch(EventListener<?> listener) {
-        // please note that we keep track of ActiveEventListeners only
-        // we do not care about other listeners
-        if(!(listener instanceof ActiveEventListener)) {
-            return;
-        }
-        synchronized (lock) {
-            counter++;
-            lock.notify();
-        }
-    }
-
-    @Override
-    public void process(EventListener<?> listener) {
-        // please note that we keep track of ActiveEventListeners only
-        // we do not care about other listeners
-        if(!(listener instanceof ActiveEventListener)) {
-            return;
-        }
-        synchronized (lock) {
-            counter--;
-            lock.notify();
-        }
-    }
-
-    /**
-     * Returns true if this event is canceled
-     *
-     * @return bool
-     */
-    public boolean canceled() {
-        return canceled.get();
-    }
-
-    /**
-     * Returns true if this event was processed by some ActiveEventListener
-     *
-     * Please note that this method returns "true" if processing did not started yet.
-     *
-     * It can be used only to detect, that processing is in progress.
-     *
-     * @return bool
-     */
-    public boolean processed() {
-        synchronized (lock) {
-            return counter == 0;
-        }
-    }
-
-    /**
-     * Waits until event is processed by some ActiveEventListener
-     *
-     * Please note that this method returns immediately if processing did not started yet.
-     *
-     * It can be used only to wait, if processing is already in progress.
-     *
-     * @return true if not canceled
-     * @throws InterruptedException if terminated
-     */
-    public boolean await() throws InterruptedException {
-        synchronized (lock) {
-            while (counter > 0) {
-                lock.wait();
-            }
-        }
-        return !canceled.get();
-    }
-}

assira.core/src/main/java/net/ranides/assira/events/ActiveEventListener.java

@@ -1,34 +0,0 @@
-package net.ranides.assira.events;
-
-/**
- * Base class for all listeners capable of process ActiveEvents
- *
- * It overrides "handleEvent" method and puts inside it additional logic marking event as processed.
- *
- * It should be abstract class with final "handleEvent", but unfortunatelly, Java supports only
- * "functional interfaces", abstract classes can't be used as lambda expressions.
- *
- * @param <T> T
- */
-public interface ActiveEventListener<T extends ActiveEvent> extends EventListener<T> {
-
-    @Override
-    default void handleEvent(T event) {
-        try {
-            if (!event.canceled()) {
-                handleActiveEvent(event);
-            }
-        } finally {
-            event.process(this);
-        }
-
-    }
-
-    /**
-     * ActiveEventListener should implement action inside this method instead of
-     * "handleEvent" which is already implemented.
-     *
-     * @param event event
-     */
-    void handleActiveEvent(T event);
-}

assira.core/src/main/java/net/ranides/assira/events/Event.java

@@ -9,35 +9,10 @@ package net.ranides.assira.events;
 /**
  * Base interface which must be implemented every class processed as event by EventListener or EventRouter.
  *
- * It is almost marker interface.
- *
- * Instance methods are by default no-ops, and there is no need to implement them.
- *
- * Only ActiveEvent implements them to keep track of processing.
- * "dispatch" is executed by dispatcher, "process" is executed by ActiveEventListener at the end of processing.
+ * It is marker interface.
  *
  * @author ranides
  */
 public interface Event {
 
-    /**
-     * This method is called by EventDispatcher just before sending event into listener.
-     * If there is more than one listener insterested in event, method will be called for each of them.
-     *
-     * ActiveEvent class keeps track of all listeners started processing using this method.
-     *
-     * @param listener listener
-     */
-    default void dispatch(EventListener<?> listener) { }
-
-    /**
-     * This method is called by ActiveEventListener at the end of "handleEvent".
-     * It is not called by other EventListener subclasses.
-     *
-     * ActiveEvent class keeps track of all listeners started and finished processing using this method.
-     *
-     * @param listener listener
-     */
-    default void process(EventListener<?> listener) { }
-
 }

assira.core/src/main/java/net/ranides/assira/events/EventDispatcher.java

@@ -264,7 +264,6 @@ public class EventDispatcher implements EventRouter {
             if( ((Class)array[i]).isAssignableFrom(clazz) ) {
                 try {
                     EventListener listener = (EventListener) array[i + 1];
-                    event.dispatch(listener);
                     if(direct) {
                         listener.handleEvent(event);
                     } else {

assira.core/src/main/java/net/ranides/assira/math/MathUtils.java

@@ -50,6 +50,18 @@ public final class MathUtils {
         return value >= min && value <= max;
     }
 
+    /**
+     * Returns true if {@code min <= value <= max}
+     *
+     * @param value value
+     * @param min min
+     * @param max max
+     * @return boolean
+     */
+    public static boolean between(double value, double min, double max) {
+        return value >= min && value <= max;
+    }
+
     /**
      * Returns value if {@code min <= value <= max}.
      * Returns min for smaller values, returns max for greater values.

assira.core/src/main/java/net/ranides/assira/reflection/IAnnotations.java

@@ -16,36 +16,101 @@ import net.ranides.assira.reflection.impl.AAnnotations;
 import net.ranides.assira.reflection.impl.FElements;
 
 /**
+ * Fluent interface for collection of Annotation objects
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */
 public interface IAnnotations extends IElements<Annotation> {
-    
+
+    /**
+     * Factory: creates new collection with annotations of provided type
+     * Every annotation inside collection has default parameter values.
+     *
+     * @param annotations types
+     * @return IAnnotations
+     */
     @SafeVarargs
     static IAnnotations of(Class<? extends Annotation>... annotations) {
         return FElements.newAnnotations(annotations);
     }
-    
+
+    /**
+     * Factory: creates new collection with provided annotations inside.
+     *
+     * @param annotations annotations
+     * @return IAnnotations
+     */
     static IAnnotations of(Annotation... annotations) {
         return FElements.newAnnotations(annotations);
     }
-    
+
+    /**
+     * Factory: returns empty collection
+     *
+     * @return IAnnotations
+     */
     static IAnnotations of() {
         return AAnnotations.EMPTY;
     }
-    
+
+    /**
+     * Returns first annotation with specified type.
+     * Returns none if not found.
+     *
+     * @param type type
+     * @param <A> A
+     * @return optional
+     */
     <A extends Annotation> Optional<A> first(Class<A> type);
 
+    /**
+     * Returns stream which contains only annotations with specified type.
+     *
+     * @param type type
+     * @param <A> A
+     * @return CQuery
+     */
     <A extends Annotation> CQuery<A> stream(Class<A> type);
 
+    /**
+     * Returns list which contains only annotations with specified type.
+     *
+     * @param type type
+     * @param <A> A
+     * @return List
+     */
     <A extends Annotation> List<A> list(Class<A> type);
 
+    /**
+     * Returns new filtered collection, with elements matching predicate
+     *
+     * @param predicate predicate
+     * @return IAnnotations
+     */
     IAnnotations require(Predicate<? super Annotation> predicate);
-    
+
+    /**
+     * Returns new filtered collection, with elements matching type
+     *
+     * @param type type
+     * @return IAnnotations
+     */
     IAnnotations require(Class<? extends Annotation> type);
-    
+
+    /**
+     * Returns new filtered collection, without elements matching predicate
+     *
+     * @param predicate predicate
+     * @return IAnnotations
+     */
     IAnnotations discard(Predicate<? super Annotation> predicate);
-    
+
+    /**
+     * Returns new filtered collection, without elements matching predicate
+     *
+     * @param type type
+     * @return IAnnotations
+     */
     IAnnotations discard(Class<? extends Annotation> type);
             
 }

assira.core/src/main/java/net/ranides/assira/reflection/IArguments.java

@@ -15,36 +15,93 @@ import net.ranides.assira.collection.query.CQuery;
 import net.ranides.assira.reflection.impl.FElements;
 
 /**
+ * Fluent interface for collection of IArgument objects
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */
 public interface IArguments extends IElements<IArgument> {
-    
+
+    /**
+     * Maps every IArgument into argument.type
+     *
+     * @return IClasses
+     */
     IClasses types();
-    
+
     @Override
     IExecutables<? extends IExecutable> parent();
-    
+
+    /**
+     * Creates map with all arguments, using argument name as a key.
+     *
+     * Please note, it can throw exception, if any argument does not store information about name.
+     *
+     * @return map
+     */
     Map<String, IArgument> map();
-    
+
+    /**
+     * Returns stream which maps every argument into java.lang.reflect.Parameter
+     *
+     * @return stream
+     */
     CQuery<Parameter> reflective();
-    
+
+    /**
+     * Factory: returns arguments for provided method
+     *
+     * @param method method
+     * @return arguments
+     */
     static IArguments typeinfo(Method method) {
         return IMethod.typeinfo(method).arguments();
     }
-    
+
+    /**
+     * Factory: returns arguments for provided constructor
+     *
+     * @param method method
+     * @return arguments
+     */
     static IArguments typeinfo(Constructor<?> method) {
         return IConstructor.typeinfo(method).arguments();
     }
-    
+
+    /**
+     * Factory: creates arguments of specified types.
+     *
+     * Please note, that information about name is not stored.
+     * Method does not create default names like "arg1, arg2, ..."
+     *
+     * @param types types
+     * @return arguments
+     */
     static IArguments typeinfo(IClass<?>... types) {
         return FElements.newArguments(types);
     }
-    
+
+    /**
+     * Factory: creates arguments of specified types.
+     *
+     * Please note, that information about name is not stored.
+     * Method does not create default names like "arg1, arg2, ..."
+     *
+     * @param types types
+     * @return arguments
+     */
     static IArguments typeinfo(Class<?>... types) {
         return FElements.newArguments(types);
     }
-    
+
+    /**
+     * Factory: creates arguments from provided map.
+     * Map keys are used as argument name, map values are used as argument type.
+     *
+     * Please note that we take OrderedMap, because order of arguments is important
+     *
+     * @param arguments arguments
+     * @return OrderedMap
+     */
     static IArguments typeinfo(OrderedMap<String, IClass<?>> arguments) {
         return FElements.newArguments(arguments);
     }

assira.core/src/main/java/net/ranides/assira/reflection/IClasses.java

@@ -13,6 +13,7 @@ import net.ranides.assira.collection.query.CQuery;
 import net.ranides.assira.reflection.impl.FElements;
 
 /**
+ * Fluent interface for collection of IClass objects
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */

assira.core/src/main/java/net/ranides/assira/reflection/IConstructors.java

@@ -14,8 +14,10 @@ import java.lang.reflect.Constructor;
 import java.util.function.Predicate;
 
 /**
+ * Fluent interface for collection of IConstructor objects
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
+ * @param <T> T
  */
 public interface IConstructors<T> extends IExecutables<IConstructor<T>> {
 

assira.core/src/main/java/net/ranides/assira/reflection/IExecutables.java

@@ -14,8 +14,10 @@ import java.lang.invoke.MethodHandle;
 import java.util.function.Predicate;
 
 /**
+ * Fluent interface for collection of IExecutable objects
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
+ * @param <T> type of executable (probably IConstructor or IMethod)
  */
 public interface IExecutables<T extends IExecutable> extends IElements<T> {
     

assira.core/src/main/java/net/ranides/assira/reflection/IFields.java

@@ -13,6 +13,7 @@ import net.ranides.assira.collection.query.CQuery;
 import net.ranides.assira.reflection.impl.FElements;
 
 /**
+ * Fluent interface for collection of IField objects
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */

assira.core/src/main/java/net/ranides/assira/reflection/IMethods.java

@@ -14,6 +14,7 @@ import java.lang.reflect.Method;
 import java.util.function.Predicate;
 
 /**
+ * Fluent interface for collection of IMethod objects
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */

assira.core/src/main/java/net/ranides/assira/reflection/IVariables.java

@@ -7,6 +7,7 @@
 package net.ranides.assira.reflection;
 
 /**
+ * Fluent interface for collection of IVariable objects
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
  */

assira.core/src/main/java/net/ranides/assira/reflection/util/AnnotationBuilder.java

@@ -17,6 +17,7 @@ import java.util.Map;
  * with specified parameters. It uses {@link AnnotationUtils} under the hood.
  *
  * @author Ranides Atterwim {@literal <ranides@gmail.com>}
+ * @param <T> T
  */
 public final class AnnotationBuilder<T extends Annotation> {