Improved documentation of classes from package org.cloudbus.cloudsim.core.predicates.

Added a @todo informing the existence of a native java.util.function.Predicate interface, suggesting the removal of the created abstract class and the use of existing interface.

Added @todo suggesting the use of HashSet instead of arrays to improve the time to match events.

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/predicates/Predicate.java

@@ -11,8 +11,16 @@ package org.cloudbus.cloudsim.core.predicates;
 import org.cloudbus.cloudsim.core.SimEvent;
 
 /**
- * Predicates are used to select events from the deferred queue. This class is abstract and must be
- * extended when writing a new predicate. Some standard predicates are provided.<br>
+ * Predicates are used to select events from the deferred queue, according to 
+ * required criteria. 
+ * They are used internally the by {@link org.cloudbus.cloudsim.core.CloudSim} class
+ * and aren't intended to be used directly by the user.
+ * 
+ * This class is abstract and must be
+ * extended when writing a new predicate. Each subclass define
+ * the criteria to select received events.
+ * 
+ * Some standard predicates are provided.<br/>
  * The idea of simulation predicates was copied from SimJava 2.
  * 
  * @author Marcos Dias de Assuncao
@@ -22,16 +30,21 @@ import org.cloudbus.cloudsim.core.SimEvent;
  * @see PredicateAny
  * @see PredicateNone
  * @see Simulation
+ * @todo It would be an interface, since it doesn't have any attributes, just 
+ * abstract methods.
+ * @todo There already is a native java {@link java.util.function.Predicate} interface.
+ * 
  */
 public abstract class Predicate {
 
 	/**
-	 * The match function which must be overridden when writing a new predicate. The function is
-	 * called with each event in the deferred queue as its parameter when a
-	 * <code>Simulation.select()</code> call is made by the user.
+         * Verifies if a given event matches the required criteria.
+	 * The method is called for each event in the deferred queue when a method such as
+	 * {@link org.cloudbus.cloudsim.core.CloudSim#select(int, org.cloudbus.cloudsim.core.predicates.Predicate) } 
+         * is called.
 	 * 
 	 * @param event The event to test for a match.
-	 * @return The function should return <code>true</code> if the event matches and should be
+	 * @return <code>true</code> if the event matches and should be
 	 *         selected, or <code>false</code> if it does not match the predicate.
 	 */
 	public abstract boolean match(SimEvent event);

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/predicates/PredicateAny.java

@@ -11,23 +11,26 @@ package org.cloudbus.cloudsim.core.predicates;
 import org.cloudbus.cloudsim.core.SimEvent;
 
 /**
- * A predicate which will match any event on the deferred event queue. There is a publicly
- * accessible instance of this predicate in <code>Simulation</code>, called
- * <code>Simulation.SIM_ANY</code>, so no new instances need to be created. <br>
+ * A predicate which will match any event on the deferred event queue. 
+ * See the publicly accessible instance of this predicate in
+ * {@link org.cloudbus.cloudsim.core.CloudSim#SIM_ANY}, so no new instances needs to be created. <br/>
  * The idea of simulation predicates was copied from SimJava 2.
  * 
  * @author Marcos Dias de Assuncao
  * @since CloudSim Toolkit 1.0
  * @see Predicate
  * @see Simulation
+ * @todo If there is only one instance of this class, it should be defined as a Singleton.
+ * The same may apply for the other predicates.
  */
 public class PredicateAny extends Predicate {
 
 	/**
-	 * The match function called by <code>Simulation</code>, not used directly by the user.
+	 * Considers there is no criteria to match an event,
+         * so any event received by the predicate will match.
 	 * 
-	 * @param ev the ev
-	 * @return true, if match
+	 * @param ev the event received
+	 * @return always true to indicate that any received event is accepted
 	 */
 	@Override
 	public boolean match(SimEvent ev) {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/predicates/PredicateFrom.java

@@ -11,7 +11,7 @@ package org.cloudbus.cloudsim.core.predicates;
 import org.cloudbus.cloudsim.core.SimEvent;
 
 /**
- * A predicate which selects events from specific entities.<br>
+ * A predicate which selects events coming from specific entities.<br/>
  * The idea of simulation predicates was copied from SimJava 2.
  * 
  * @author Marcos Dias de Assuncao
@@ -21,7 +21,7 @@ import org.cloudbus.cloudsim.core.SimEvent;
  */
 public class PredicateFrom extends Predicate {
 
-	/** The ids. */
+	/** The IDs of source entities to check the reception of events from. */
 	private final int[] ids;
 
 	/**
@@ -43,14 +43,23 @@ public class PredicateFrom extends Predicate {
 	}
 
 	/**
-	 * The match function called by <code>Simulation</code>, not used directly by the user.
+	 * Matches any event received from the registered sources.
 	 * 
 	 * @param ev the event to check
 	 * @return <code>true</code> if the event matches the predicate, <code>false</code> otherwise
+         * @see #ids
 	 */
 	@Override
 	public boolean match(SimEvent ev) {
 		int src = ev.getSource();
+                /*
+                @todo Instead of using an array where each position stores
+                the id of an entity (that requires a loop over the array, it would be 
+                used a HashSet (Set interface) to reduce the time
+                to match the event. 
+                This should be applied to the other implementations
+                of the super class.
+                */
 		for (int id : ids) {
 			if (src == id) {
 				return true;

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/predicates/PredicateNone.java

@@ -11,10 +11,10 @@ package org.cloudbus.cloudsim.core.predicates;
 import org.cloudbus.cloudsim.core.SimEvent;
 
 /**
- * A predicate which will <b>not</b> match any event on the deferred event queue. There is a
- * publicly accessible instance of this predicate in the {@link Simulation} class, called
- * {@link Simulation#SIM_NONE}, so the user does not need to create any new instances. The idea of
- * simulation predicates was copied from SimJava 2.
+ * A predicate which will <b>not</b> match any event on the deferred event queue. 
+ * See the publicly accessible instance of this predicate in
+ * {@link org.cloudbus.cloudsim.core.CloudSim#SIM_NONE}, so no new instances needs to be created. <br/>
+ * The idea of simulation predicates was copied from SimJava 2.
  * 
  * @author Marcos Dias de Assuncao
  * @since CloudSim Toolkit 1.0
@@ -24,10 +24,10 @@ import org.cloudbus.cloudsim.core.SimEvent;
 public class PredicateNone extends Predicate {
 
 	/**
-	 * The match function called by {@link Simulation}, not used directly by the user.
+	 * Considers that no event received by the predicate matches.
 	 * 
-	 * @param ev the event to check
-	 * @return <code>true</code> if the event matches the predicate, <code>false</code> otherwise
+	 * @param ev the event received
+	 * @return always false to indicate that no event is accepted
 	 */
 	@Override
 	public boolean match(SimEvent ev) {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/predicates/PredicateNotFrom.java

@@ -20,7 +20,7 @@ import org.cloudbus.cloudsim.core.SimEvent;
  */
 public class PredicateNotFrom extends Predicate {
 
-	/** The ids. */
+	/** The IDs of source entities to check if events were not sent from. */
 	private final int[] ids;
 
 	/**
@@ -42,10 +42,11 @@ public class PredicateNotFrom extends Predicate {
 	}
 
 	/**
-	 * The match function called by {@link Simulation}, not used directly by the user.
+	 * Matches any event <b>not</b> received from the registered sources.
 	 * 
 	 * @param ev the event to check
 	 * @return <code>true</code> if the event matches the predicate, <code>false</code> otherwise
+         * @see #ids
 	 */
 	@Override
 	public boolean match(SimEvent ev) {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/predicates/PredicateNotType.java

@@ -20,7 +20,7 @@ import org.cloudbus.cloudsim.core.SimEvent;
  */
 public class PredicateNotType extends Predicate {
 
-	/** The tags. */
+	/** Array of tags to verify if the tag of received events doesn't correspond to. */
 	private final int[] tags;
 
 	/**
@@ -42,10 +42,11 @@ public class PredicateNotType extends Predicate {
 	}
 
 	/**
-	 * The match function called by {@link Simulation}, not used directly by the user.
+	 * Matches any event that hasn't one of the specified {@link #tags}.
 	 * 
-	 * @param ev the ev
-	 * @return true, if match
+	 * @param ev the event to check
+	 * @return <code>true</code> if the event matches the predicate, <code>false</code> otherwise
+         * @see #tags
 	 */
 	@Override
 	public boolean match(SimEvent ev) {

modules/cloudsim/src/main/java/org/cloudbus/cloudsim/core/predicates/PredicateType.java

@@ -20,11 +20,11 @@ import org.cloudbus.cloudsim.core.SimEvent;
  */
 public class PredicateType extends Predicate {
 
-	/** The tags. */
+	/** Array of tags to verify if the tag of received events correspond to. */
 	private final int[] tags;
 
 	/**
-	 * Constructor used to select events with the tag value <code>t1</code>.
+	 * Constructor used to select events with the given tag value.
 	 * 
 	 * @param t1 an event tag value
 	 */
@@ -42,10 +42,11 @@ public class PredicateType extends Predicate {
 	}
 
 	/**
-	 * The match function called by <code>Sim_system</code>, not used directly by the user.
+	 * Matches any event that has one of the specified {@link #tags}.
 	 * 
-	 * @param ev the ev
-	 * @return true, if match
+	 * @param ev the event to check
+	 * @return <code>true</code> if the event matches the predicate, <code>false</code> otherwise
+         * @see #tags
 	 */
 	@Override
 	public boolean match(SimEvent ev) {