Commit e0334f46 authored by Manoel Campos's avatar Manoel Campos

Improved documentation of classes from package org.cloudbus.cloudsim.lists.

Included some @todo's suggesting the assessment of some methods used to find an object inside a List in order to reduce search time. One option is to change some List objects by a HashMap. Other details can be seen at the @todo's inside the source code.
parent ce7712d0
...@@ -29,8 +29,8 @@ public class GammaDistr implements ContinuousDistribution { ...@@ -29,8 +29,8 @@ public class GammaDistr implements ContinuousDistribution {
* Instantiates a new Gamma pseudo random number generator. * Instantiates a new Gamma pseudo random number generator.
* *
* @param seed the seed * @param seed the seed
* @param alpha the alpha * @param shape the shape
* @param beta the beta * @param scale the scale
*/ */
public GammaDistr(Random seed, int shape, double scale) { public GammaDistr(Random seed, int shape, double scale) {
this(shape, scale); this(shape, scale);
...@@ -40,8 +40,8 @@ public class GammaDistr implements ContinuousDistribution { ...@@ -40,8 +40,8 @@ public class GammaDistr implements ContinuousDistribution {
/** /**
* Instantiates a new Gamma pseudo random number generator. * Instantiates a new Gamma pseudo random number generator.
* *
* @param alpha the alpha * @param shape the shape
* @param beta the beta * @param scale the scale
*/ */
public GammaDistr(int shape, double scale) { public GammaDistr(int shape, double scale) {
numGen = new GammaDistribution(shape, scale); numGen = new GammaDistribution(shape, scale);
......
...@@ -30,8 +30,8 @@ public class LognormalDistr implements ContinuousDistribution { ...@@ -30,8 +30,8 @@ public class LognormalDistr implements ContinuousDistribution {
* Instantiates a new Log-normal pseudo random number generator. * Instantiates a new Log-normal pseudo random number generator.
* *
* @param seed the seed * @param seed the seed
* @param mean the mean * @param shape the shape
* @param dev the dev * @param scale the scale
*/ */
public LognormalDistr(Random seed, double shape, double scale) { public LognormalDistr(Random seed, double shape, double scale) {
this(shape, scale); this(shape, scale);
...@@ -41,8 +41,8 @@ public class LognormalDistr implements ContinuousDistribution { ...@@ -41,8 +41,8 @@ public class LognormalDistr implements ContinuousDistribution {
/** /**
* Instantiates a new Log-normal pseudo random number generator. * Instantiates a new Log-normal pseudo random number generator.
* *
* @param mean the mean * @param shape the shape
* @param dev the dev * @param scale the scale
*/ */
public LognormalDistr(double shape, double scale) { public LognormalDistr(double shape, double scale) {
numGen = new LogNormalDistribution(scale, shape); numGen = new LogNormalDistribution(scale, shape);
......
...@@ -23,11 +23,11 @@ import org.cloudbus.cloudsim.Cloudlet; ...@@ -23,11 +23,11 @@ import org.cloudbus.cloudsim.Cloudlet;
public class CloudletList { public class CloudletList {
/** /**
* Gets the by id. * Gets a {@link Cloudlet} with a given id.
* *
* @param cloudletList the cloudlet list * @param cloudletList the list of existing Cloudlets
* @param id the id * @param id the Cloudlet id
* @return the by id * @return a Cloudlet with the given ID or $null if not found
*/ */
public static <T extends Cloudlet> T getById(List<T> cloudletList, int id) { public static <T extends Cloudlet> T getById(List<T> cloudletList, int id) {
for (T cloudlet : cloudletList) { for (T cloudlet : cloudletList) {
...@@ -39,10 +39,11 @@ public class CloudletList { ...@@ -39,10 +39,11 @@ public class CloudletList {
} }
/** /**
* Returns the position of the cloudlet with that id, if it exists. Otherwise -1. * Gets the position of a cloudlet with a given id.
* @param cloudletList - the list of cloudlets. *
* @param id - the id we search for. * @param cloudletList the list of existing cloudlets
* @return - the position of the cloudlet with that id, or -1 otherwise. * @param id the cloudlet id
* @return the position of the cloudlet with the given id or -1 if not found
*/ */
public static <T extends Cloudlet> int getPositionById(List<T> cloudletList, int id) { public static <T extends Cloudlet> int getPositionById(List<T> cloudletList, int id) {
int i = 0 ; int i = 0 ;
......
...@@ -21,13 +21,12 @@ import org.cloudbus.cloudsim.Host; ...@@ -21,13 +21,12 @@ import org.cloudbus.cloudsim.Host;
public class HostList { public class HostList {
/** /**
* Gets the host (PM) object for a particular ID. * Gets a {@link Host} with a given id.
* *
* @param <T> the generic type * @param <T> the generic type
* @param hostList the host list * @param hostList the list of existing hosts
* @param id the host ID * @param id the host ID
* @return the host object or <tt>null</tt> if no host exists * @return a Host with the given ID or $null if not found
* @see gridsim.Machine
* *
* @pre id >= 0 * @pre id >= 0
* @post $none * @post $none
...@@ -42,11 +41,11 @@ public class HostList { ...@@ -42,11 +41,11 @@ public class HostList {
} }
/** /**
* Gets the total number of PEs for all PMs. * Gets the total number of PEs for all Hosts.
* *
* @param <T> the generic type * @param <T> the generic type
* @param hostList the host list * @param hostList the list of existing hosts
* @return number of PEs * @return total number of PEs for all PMs
* @pre $none * @pre $none
* @post $result >= 0 * @post $result >= 0
*/ */
...@@ -59,11 +58,11 @@ public class HostList { ...@@ -59,11 +58,11 @@ public class HostList {
} }
/** /**
* Gets the total number of <tt>FREE</tt> or non-busy PEs for all PMs. * Gets the total number of <tt>FREE</tt> (non-busy) PEs for all Hosts.
* *
* @param <T> the generic type * @param <T> the generic type
* @param hostList the host list * @param hostList the list of existing hosts
* @return number of PEs * @return total number of free PEs
* @pre $none * @pre $none
* @post $result >= 0 * @post $result >= 0
*/ */
...@@ -76,11 +75,11 @@ public class HostList { ...@@ -76,11 +75,11 @@ public class HostList {
} }
/** /**
* Gets the total number of <tt>BUSY</tt> PEs for all PMs. * Gets the total number of <tt>BUSY</tt> PEs for all Hosts.
* *
* @param <T> the generic type * @param <T> the generic type
* @param hostList the host list * @param hostList the list of existing hosts
* @return number of PEs * @return total number of busy PEs
* @pre $none * @pre $none
* @post $result >= 0 * @post $result >= 0
*/ */
...@@ -93,11 +92,11 @@ public class HostList { ...@@ -93,11 +92,11 @@ public class HostList {
} }
/** /**
* Gets the first host with free Pe's. * Gets the first host with free PEs.
* *
* @param <T> the generic type * @param <T> the generic type
* @param hostList the host list * @param hostList the list of existing hosts
* @return a machine object or <tt>null</tt> if not found * @return a Host object or <tt>null</tt> if not found
* @pre $none * @pre $none
* @post $none * @post $none
*/ */
...@@ -106,12 +105,12 @@ public class HostList { ...@@ -106,12 +105,12 @@ public class HostList {
} }
/** /**
* Gets the first PM with a specified number of free Pe's. * Gets the first Host with a specified number of free PEs.
* *
* @param <T> the generic type * @param <T> the generic type
* @param hostList the host list * @param hostList the list of existing hosts
* @param pesNumber the pes number * @param pesNumber the pes number
* @return a machine object or <tt>null</tt> if not found * @return a Host object or <tt>null</tt> if not found
* @pre $none * @pre $none
* @post $none * @post $none
*/ */
...@@ -125,17 +124,17 @@ public class HostList { ...@@ -125,17 +124,17 @@ public class HostList {
} }
/** /**
* Sets the particular Pe status on a PM. * Sets the status of a particular PE on a given Host.
* *
* @param <T> the generic type * @param <T> the generic type
* @param hostList the host list * @param hostList the list of existing hosts
* @param status Pe status, either <tt>Pe.FREE</tt> or <tt>Pe.BUSY</tt> * @param status the PE status, either <tt>Pe.FREE</tt> or <tt>Pe.BUSY</tt>
* @param hostId the host id * @param hostId the host id
* @param peId the pe id * @param peId the id of the PE to set the status
* @return <tt>true</tt> if the Pe status has changed, <tt>false</tt> otherwise (host id or * @return <tt>true</tt> if the PE status has changed, <tt>false</tt> otherwise (host id or
* Pe id might not be exist) * PE id might not be exist)
* @pre machineID >= 0 * @pre hostId >= 0
* @pre peID >= 0 * @pre peId >= 0
* @post $none * @post $none
*/ */
public static <T extends Host> boolean setPeStatus(List<T> hostList, int status, int hostId, int peId) { public static <T extends Host> boolean setPeStatus(List<T> hostList, int status, int hostId, int peId) {
......
...@@ -23,11 +23,11 @@ import org.cloudbus.cloudsim.Vm; ...@@ -23,11 +23,11 @@ import org.cloudbus.cloudsim.Vm;
public class PeList { public class PeList {
/** /**
* Gets a Pe by its id. * Gets a {@link Pe} with a given id.
* *
* @param peList the PE list where to get a given PE * @param peList the PE list where to get a given PE
* @param id the id of the PE to be get * @param id the id of the PE to be get
* @return the PE if the given id or null if not found * @return the PE with the given id or null if not found
* @pre id >= 0 * @pre id >= 0
* @post $none * @post $none
*/ */
...@@ -45,7 +45,7 @@ public class PeList { ...@@ -45,7 +45,7 @@ public class PeList {
} }
/** /**
* Gets MIPS Rating of a PE with a specified ID. * Gets MIPS Rating of a PE with a given ID.
* *
* @param peList the PE list where to get a given PE * @param peList the PE list where to get a given PE
* @param id the id of the PE to be get * @param id the id of the PE to be get
...@@ -78,10 +78,10 @@ public class PeList { ...@@ -78,10 +78,10 @@ public class PeList {
} }
/** /**
* Gets the max utilization percentage among by all PEs. * Gets the max utilization percentage among all PEs.
* *
* @param peList the pe list * @param peList the pe list
* @return the utilization percentage * @return the max utilization percentage
*/ */
public static <T extends Pe> double getMaxUtilization(List<T> peList) { public static <T extends Pe> double getMaxUtilization(List<T> peList) {
double maxUtilization = 0; double maxUtilization = 0;
...@@ -95,11 +95,11 @@ public class PeList { ...@@ -95,11 +95,11 @@ public class PeList {
} }
/** /**
* Gets the max utilization percentage among by all PEs allocated to a VM. * Gets the max utilization percentage among all PEs allocated to a VM.
* *
* @param vm the vm to get the maximum utilization percentage * @param vm the vm to get the maximum utilization percentage
* @param peList the pe list * @param peList the pe list
* @return the utilization percentage * @return the max utilization percentage
*/ */
public static <T extends Pe> double getMaxUtilizationAmongVmsPes(List<T> peList, Vm vm) { public static <T extends Pe> double getMaxUtilizationAmongVmsPes(List<T> peList, Vm vm) {
double maxUtilization = 0; double maxUtilization = 0;
...@@ -116,10 +116,10 @@ public class PeList { ...@@ -116,10 +116,10 @@ public class PeList {
} }
/** /**
* Gets the first PE which is FREE. * Gets the first <tt>FREE</tt> PE which.
* *
* @param peList the PE list * @param peList the PE list
* @return the first free PE, otherwise returns null * @return the first free PE or null if not found
* @pre $none * @pre $none
* @post $none * @post $none
*/ */
...@@ -133,7 +133,7 @@ public class PeList { ...@@ -133,7 +133,7 @@ public class PeList {
} }
/** /**
* Gets the number of <tt>FREE</tt> or non-busy PEs. * Gets the number of <tt>FREE</tt> (non-busy) PEs.
* *
* @param peList the PE list * @param peList the PE list
* @return number of free PEs * @return number of free PEs
...@@ -153,7 +153,7 @@ public class PeList { ...@@ -153,7 +153,7 @@ public class PeList {
/** /**
* Sets a PE status. * Sets a PE status.
* *
* @param status PE status, either <tt>Pe.FREE</tt> or <tt>Pe.BUSY</tt> * @param status the PE status, either <tt>Pe.FREE</tt> or <tt>Pe.BUSY</tt>
* @param id the id of the PE to be set * @param id the id of the PE to be set
* @param peList the PE list * @param peList the PE list
* @return <tt>true</tt> if the PE status has been changed, <tt>false</tt> otherwise (PE id might * @return <tt>true</tt> if the PE status has been changed, <tt>false</tt> otherwise (PE id might
...@@ -190,14 +190,15 @@ public class PeList { ...@@ -190,14 +190,15 @@ public class PeList {
/** /**
* Sets the status of PEs of a host to FAILED or FREE. NOTE: <tt>resName</tt> and * Sets the status of PEs of a host to FAILED or FREE. NOTE: <tt>resName</tt> and
* <tt>machineID</tt> are used for debugging purposes, which is <b>ON</b> by default. * <tt>hostId</tt> are used for debugging purposes, which is <b>ON</b> by default.
* Use {@link #setStatusFailed(boolean)} if you do not want this information. * Use {@link #setStatusFailed(boolean)} if you do not want this information.
* *
* @param peList the host's PE list to be set as failed or free * @param peList the host's PE list to be set as failed or free
* @param resName the name of the resource * @param resName the name of the resource
* @param hostId the id of this host * @param hostId the id of the host
* @param failed true if the host's PEs have to be set as FAILED, false * @param failed true if the host's PEs have to be set as FAILED, false
* if they have to be set as FREE. * if they have to be set as FREE.
* @see #setStatusFailed(java.util.List, boolean)
*/ */
public static <T extends Pe> void setStatusFailed( public static <T extends Pe> void setStatusFailed(
List<T> peList, List<T> peList,
......
...@@ -21,18 +21,20 @@ import org.cloudbus.cloudsim.ResCloudlet; ...@@ -21,18 +21,20 @@ import org.cloudbus.cloudsim.ResCloudlet;
public class ResCloudletList { public class ResCloudletList {
/** /**
* Returns a given Cloudlet. This method needs a combination of Cloudlet Id and User Id because * Gets a {@link ResCloudlet} with a given id and owned by a given user.
* each Cloud Users might have exactly same Cloudlet Ids. * This method needs a combination of Cloudlet Id and User Id because
* each Cloud User might have exactly the same Cloudlet Id.
* *
* @param cloudletId a Cloudlet Id * @param cloudletId a Cloudlet Id
* @param userId an User Id * @param userId an User Id
* @param list the list * @param list the list of ResCloudlet
* @return the Cloudlet. * @return a Cloudlet or null if not found
* @throws IndexOutOfBoundsException - if a Cloudlet with specified Id and user id is not in the
* list.
* @pre cloudletId >= 0 * @pre cloudletId >= 0
* @pre userId >= 0 * @pre userId >= 0
* @post $none * @post $none
*
* @todo The second phrase of the class documentation is not clear.
*/ */
public static <T extends ResCloudlet> ResCloudlet getByIdAndUserId( public static <T extends ResCloudlet> ResCloudlet getByIdAndUserId(
List<T> list, List<T> list,
...@@ -47,14 +49,15 @@ public class ResCloudletList { ...@@ -47,14 +49,15 @@ public class ResCloudletList {
} }
/** /**
* Finds the index of a Cloudlet inside the list. This method needs a combination of Cloudlet Id * Finds the index of a ResCloudlet inside a list.
* This method needs a combination of Cloudlet Id
* and User Id because each Cloud User might have exactly the same Cloudlet Id. * and User Id because each Cloud User might have exactly the same Cloudlet Id.
* *
* @param cloudletId a Cloudlet Id * @param cloudletId a Cloudlet Id
* @param userId an User Id * @param userId an User Id
* @param list the list * @param list the list of ResCloudlets
* @return the index in this list of the first occurrence of the specified Cloudlet, or * @return the index in this list of the first occurrence of the specified Cloudlet, or
* <code>-1</code> if the list does not contain this Cloudlet. * <code>-1</code> if the list does not contain the Cloudlet.
* @pre cloudletId >= 0 * @pre cloudletId >= 0
* @pre userId >= 0 * @pre userId >= 0
* @post $none * @post $none
...@@ -71,12 +74,12 @@ public class ResCloudletList { ...@@ -71,12 +74,12 @@ public class ResCloudletList {
} }
/** /**
* Move a ResCloudlet object from this linked-list into a specified one. * Moves a ResCloudlet object from a list to another.
* *
* @param listFrom the list from * @param listFrom the source list
* @param listTo the list to * @param listTo the destination list
* @param cloudlet the cloudlet * @param cloudlet the cloudlet to be moved from the source to the destination list
* @return <b>true</b> if the moving operation successful, otherwise return <b>false</b> * @return <b>true</b> if the moving operation successful, <b>false</b> otherwise
* @pre obj != null * @pre obj != null
* @pre list != null * @pre list != null
* @post $result == true || $result == false * @post $result == true || $result == false
...@@ -90,10 +93,11 @@ public class ResCloudletList { ...@@ -90,10 +93,11 @@ public class ResCloudletList {
} }
/** /**
* Returns the position of the cloudlet with that id, if it exists. Otherwise -1. * Gets the position of a ResCloudlet with a given id.
* @param cloudletList - the list of cloudlets. *
* @param id - the id we search for. * @param cloudletList the list of cloudlets.
* @return - the position of the cloudlet with that id, or -1 otherwise. * @param id the cloudlet id
* @return the position of the cloudlet with that id, or -1 if not found.
*/ */
public static <T extends ResCloudlet> int getPositionById(List<T> cloudletList, int id) { public static <T extends ResCloudlet> int getPositionById(List<T> cloudletList, int id) {
int i = 0 ; int i = 0 ;
......
...@@ -21,13 +21,30 @@ import org.cloudbus.cloudsim.Vm; ...@@ -21,13 +21,30 @@ import org.cloudbus.cloudsim.Vm;
public class VmList { public class VmList {
/** /**
* Return a reference to a Vm object from its ID. * Gets a {@link Vm} with a given id.
* *
* @param id ID of required VM * @param id ID of required VM
* @param vmList the vm list * @param vmList list of existing VMs
* @return Vm with the given ID, $null if not found * @return a Vm with the given ID or $null if not found
* @pre $none * @pre $none
* @post $none * @post $none
*
* @todo It may be considered the use of a HashMap in order to improve
* VM search, instead of a List. The map key can be the vm id
* and the value the VM itself. However, it has to be assessed
* the feasibility to have VMs with the same ID and the need
* to find VMs by its id and user id, as in the method
* {@link #getByIdAndUserId(java.util.List, int, int)}.
* The first concern could be dealt by ensuring that all
* VMs have different ID (in fact, I don't know if
* VM id uniqueness is a CloudSim requirement)
* and creating a map by VM id.
* The second concern could be dealt by creating
* a HashMap<UserID, List<VmIDs>>.
* The third concern is, that changing
* the class of these lists may have a potential
* effect on the entire project and in the creation of simulations
* that has to be priorly assessed.
*/ */
public static <T extends Vm> T getById(List<T> vmList, int id) { public static <T extends Vm> T getById(List<T> vmList, int id) {
for (T vm : vmList) { for (T vm : vmList) {
...@@ -39,11 +56,11 @@ public class VmList { ...@@ -39,11 +56,11 @@ public class VmList {
} }
/** /**
* Return a reference to a Vm object from its ID and user ID. * Gets a {@link Vm} with a given id and owned by a given user.
* *
* @param vmList list of existing VMs
* @param id ID of required VM * @param id ID of required VM
* @param userId the user ID * @param userId the user ID of the VM's owner
* @param vmList the vm list
* @return Vm with the given ID, $null if not found * @return Vm with the given ID, $null if not found
* @pre $none * @pre $none
* @post $none * @post $none
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment