You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@uima.apache.org by ch...@apache.org on 2015/04/17 20:39:51 UTC
svn commit: r1674377 - in /uima/sandbox/uima-ducc/trunk:
uima-ducc-cli/src/main/java/org/apache/uima/ducc/cli/
uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/
uima-ducc-common/src/main/java/org/apache/uima/ducc/common/main/ uima...
Author: challngr
Date: Fri Apr 17 18:39:51 2015
New Revision: 1674377
URL: http://svn.apache.org/r1674377
Log:
UIMA-4109 Update javadoc for RM API and fix other javadoc errors.
Modified:
uima/sandbox/uima-ducc/trunk/uima-ducc-cli/src/main/java/org/apache/uima/ducc/cli/AServicePing.java
uima/sandbox/uima-ducc/trunk/uima-ducc-cli/src/main/java/org/apache/uima/ducc/cli/CliBase.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/DuccAdminEvent.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQLoad.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQLoadReply.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQOccupancy.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQOccupancyReply.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminReconfigure.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminReply.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminVaryOff.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminVaryOn.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedClass.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedMachine.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedNodepool.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedShare.java
uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/main/DuccRmAdmin.java
uima/sandbox/uima-ducc/trunk/uima-ducc-rm/src/main/java/org/apache/uima/ducc/rm/scheduler/Scheduler.java
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-cli/src/main/java/org/apache/uima/ducc/cli/AServicePing.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-cli/src/main/java/org/apache/uima/ducc/cli/AServicePing.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-cli/src/main/java/org/apache/uima/ducc/cli/AServicePing.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-cli/src/main/java/org/apache/uima/ducc/cli/AServicePing.java Fri Apr 17 18:39:51 2015
@@ -141,7 +141,7 @@ public abstract class AServicePing
* @param endpoint This is the name of the service endpoint, as passed in
* at service registration.
*
- * @param initProps Properties file with static data about the service and
+ * @param initState Properties file with static data about the service and
* pinger.
*/
public void init(String arguments, String endpoint, Map<String, Object> initState)
@@ -204,7 +204,7 @@ public abstract class AServicePing
* run-failures Integer Total run failures since the service was started
* </xmp>
*
- * @eturn A Map<String, Object> of string-key to Object containing dynamic information from the SM. Callers
+ * @return A Map<String, Object> of string-key to Object containing dynamic information from the SM. Callers
* must cast the value to the correct type as shown below.
*/
public Map<String, Object> getSmState()
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-cli/src/main/java/org/apache/uima/ducc/cli/CliBase.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-cli/src/main/java/org/apache/uima/ducc/cli/CliBase.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-cli/src/main/java/org/apache/uima/ducc/cli/CliBase.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-cli/src/main/java/org/apache/uima/ducc/cli/CliBase.java Fri Apr 17 18:39:51 2015
@@ -495,7 +495,7 @@ public abstract class CliBase
* structures for the API, and extracts the numeric id of the [job, ducclet, reservation, service]
* returned by the Orchestrator.
*
- * @returns true if the action succeeded and false otherwise. The action in this case, is whatever
+ * @return true if the action succeeded and false otherwise. The action in this case, is whatever
* the Orchestrator was asked to do: submit something, cancel something, etc.
*/
boolean extractReply(AbstractDuccOrchestratorEvent reply)
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/DuccAdminEvent.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/DuccAdminEvent.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/DuccAdminEvent.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/DuccAdminEvent.java Fri Apr 17 18:39:51 2015
@@ -20,29 +20,48 @@ package org.apache.uima.ducc.common.admi
import java.io.Serializable;
+/**
+ * This class provides the abstraction for requests to DUCC's administrative interface.
+ */
public abstract class DuccAdminEvent implements Serializable
{
private static final long serialVersionUID = 1753129558912646806L;
- String user;
- byte[] auth_block;
+ private String user;
+ private byte[] auth_block;
@SuppressWarnings("unused")
private DuccAdminEvent() // prevent use of this, only the form with user and auth_block is allowed
{
}
+ /**
+ * Create a request to send to DUCC.
+ *
+ * @param user This is the id of the user making the request.
+ *
+ * @param auth_block This is the authentication block as returned by {@link org.apache.uima.ducc.common.crypto.Crypto Crypto}. The receiver
+ * will validate the messsage and if the <code>auth_block</code> does not match what receiver expects,
+ * the request is denied. Nota that this is NOT intended to provide foolproof security. It's only
+ * intention is to provde basic authentication of the user (is the user who he claims to be?).
+ */
protected DuccAdminEvent(String user, byte[] auth_block)
{
this.user = user;
this.auth_block = auth_block;
}
+ /**
+ * Return the id of the user making the request.
+ */
public String getUser()
{
return user;
}
+ /**
+ * Return the authentication block for the request.
+ */
public byte[] getAuthBlock()
{
return auth_block;
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQLoad.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQLoad.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQLoad.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQLoad.java Fri Apr 17 18:39:51 2015
@@ -18,6 +18,9 @@
*/
package org.apache.uima.ducc.common.admin.event;
+/**
+ * Construct and send this event to query the current load and resource status of the RM.
+ */
public class RmAdminQLoad
extends DuccAdminEvent
{
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQLoadReply.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQLoadReply.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQLoadReply.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQLoadReply.java Fri Apr 17 18:39:51 2015
@@ -21,6 +21,9 @@ package org.apache.uima.ducc.common.admi
import java.util.ArrayList;
import java.util.List;
+/**
+ * This event returns the response of a RmAdminQLoad request.
+ */
public class RmAdminQLoadReply
extends RmAdminReply
{
@@ -37,28 +40,36 @@ public class RmAdminQLoadReply
}
+ /** RM only, other use produces incorrect results. */
public void setShareQuantum(long q) { this.shareQuantum = q / ( 1024*1024); }
+ /** RM only, other use produces incorrect results. */
public void addNodepool (RmQueriedNodepool np) { nodepools.add(np); }
+ /** RM only, other use produces incorrect results. */
public void addClass (RmQueriedClass cl) { classes.add(cl); }
+ /**
+ * Return the share quantum currently being used by RM.
+ */
public long getShareQuantum() { return shareQuantum; }
+
+ /**
+ * @return the {@link RmQueriedNodepool nodepool} details.
+ */
public List<RmQueriedNodepool> getNodepools() { return nodepools; }
+
+ /**
+ * @return The {@link RmQueriedNodepool class} details.
+ */
public List<RmQueriedClass> getClasses() { return classes; }
+ /** RM only, other use produces incorrect results. */
public void notReady() { this.ready = false; }
- public boolean isReady() { return ready; }
- public static String fmtArray(int[] array)
- {
- Object[] vals = new Object[array.length];
- StringBuffer sb = new StringBuffer();
-
- for ( int i = 0; i < array.length; i++ ) {
- sb.append("%3s ");
- vals[i] = Integer.toString(array[i]);
- }
- return String.format(sb.toString(), vals);
- }
+ /**
+ * @return True if RM is able to schedule and be queried, false otherwise. If the RM is not yet
+ * ready to schedule, e.g. immediately after boot or reconfigure, this method will return false.
+ */
+ public boolean isReady() { return ready; }
/**
The compact format creates a Python structure of this form:
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQOccupancy.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQOccupancy.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQOccupancy.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQOccupancy.java Fri Apr 17 18:39:51 2015
@@ -18,6 +18,9 @@
*/
package org.apache.uima.ducc.common.admin.event;
+/**
+ * Construct and send this event to query the current host status of the RM.
+ */
public class RmAdminQOccupancy
extends DuccAdminEvent
{
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQOccupancyReply.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQOccupancyReply.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQOccupancyReply.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminQOccupancyReply.java Fri Apr 17 18:39:51 2015
@@ -23,6 +23,9 @@ import java.util.Collections;
import java.util.Comparator;
import java.util.List;
+/**
+ * This event returns detailed information on the scheduling state of each active host.
+ */
public class RmAdminQOccupancyReply
extends RmAdminReply
{
@@ -41,7 +44,15 @@ public class RmAdminQOccupancyReply
machines.add(m);
}
+ /**
+ * Used by RM only.
+ */
public void notReady() { this.ready = false; }
+
+ /**
+ * @return True if RM is able to schedule and be queried, false otherwise. If the RM is not yet
+ * ready to schedule, e.g. immediately after boot or reconfigure, this method will return false.
+ */
public boolean isReady() { return ready; }
public List<RmQueriedMachine> getMachines()
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminReconfigure.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminReconfigure.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminReconfigure.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminReconfigure.java Fri Apr 17 18:39:51 2015
@@ -19,6 +19,9 @@
package org.apache.uima.ducc.common.admin.event;
// UIMA-4142
+/**
+ * Construct and send this event to cause the RM to reread its configuraton.
+ */
public class RmAdminReconfigure
extends DuccAdminEvent
{
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminReply.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminReply.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminReply.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminReply.java Fri Apr 17 18:39:51 2015
@@ -20,6 +20,9 @@ package org.apache.uima.ducc.common.admi
import java.io.Serializable;
+/**
+ * This is a generic response packet to the RM Administrative interface.
+ */
public class RmAdminReply
implements Serializable
{
@@ -31,6 +34,9 @@ public class RmAdminReply
this.response = response;
}
+ /**
+ * @return a string with the RM's response message.
+ */
public String getResponse()
{
return response;
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminVaryOff.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminVaryOff.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminVaryOff.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminVaryOff.java Fri Apr 17 18:39:51 2015
@@ -18,12 +18,22 @@
*/
package org.apache.uima.ducc.common.admin.event;
+/**
+ * Construct and send this event to vary off a set of hosts.
+ */
public class RmAdminVaryOff
extends DuccAdminEvent
{
private static final long serialVersionUID = -8101741014979144426L;
- String[] nodes;
+ private String[] nodes;
+ /**
+ * This build a request to vary off a set of hosts.
+ *
+ * @param nodes This is a string array containing the names of the hosts to vary off.
+ * @param user This is the name of the user making the request, as required by the superclass.
+ * @param auth This is the authentication block for the request, as required by the superclass.
+ */
public RmAdminVaryOff(String[] nodes, String user, byte[] auth)
{
super(user, auth);
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminVaryOn.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminVaryOn.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminVaryOn.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmAdminVaryOn.java Fri Apr 17 18:39:51 2015
@@ -18,12 +18,22 @@
*/
package org.apache.uima.ducc.common.admin.event;
+/**
+ * Use this event to cause RM to vary on a set of hosts.
+ */
public class RmAdminVaryOn
extends DuccAdminEvent
{
private static final long serialVersionUID = -8101741014979144426L;
String[] nodes;
+ /**
+ * This build a request to vary on a set of hosts.
+ *
+ * @param nodes This is a string array containing the names of the hosts to vary off.
+ * @param user This is the name of the user making the request, as required by the superclass.
+ * @param auth This is the authentication block for the request, as required by the superclass.
+ */
public RmAdminVaryOn(String[] nodes, String user, byte[] auth)
{
super(user, auth);
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedClass.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedClass.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedClass.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedClass.java Fri Apr 17 18:39:51 2015
@@ -21,6 +21,11 @@ package org.apache.uima.ducc.common.admi
import java.io.Serializable;
import java.util.Arrays;
+/**
+ * This object represents, for each class, the number of shares that are being requested of it, and
+ * the number of shares that have been awarded to requestsin this class, broken down by multiples
+ * of the share quantum (in essence number of processes broken down by size).
+ */
public class RmQueriedClass
implements Serializable
{
@@ -35,6 +40,9 @@ public class RmQueriedClass
{
}
+ /**
+ * @return the name of the class.
+ */
public String getName() {
return name;
}
@@ -44,6 +52,12 @@ public class RmQueriedClass
this.name = name;
}
+ /**
+ * @return the scheduling policy for the class:
+ * FAIR_SHARE
+ * FIXED_SHARE
+ * RESERVE
+ */
public String getPolicy() {
return policy;
}
@@ -52,6 +66,10 @@ public class RmQueriedClass
this.policy = policy;
}
+ /**
+ * @return an array, indexed by multiples of the share quantum, showing the number of requests of each size
+ * currently demanded by the workload.
+ */
public int[] getDemanded() {
return demanded;
}
@@ -62,6 +80,10 @@ public class RmQueriedClass
}
+ /**
+ * @return an array, indexed by multiples of the share quantum, showing the number of requests of each size
+ * currently awared to requests in the class.
+ */
public int[] getAwarded() {
return awarded;
}
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedMachine.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedMachine.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedMachine.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedMachine.java Fri Apr 17 18:39:51 2015
@@ -22,10 +22,13 @@ import java.io.Serializable;
import java.util.ArrayList;
import java.util.List;
+/**
+ * This object represents details of a host as seen by the Resource Manager.
+ */
public class RmQueriedMachine
implements Serializable
{
- private static final long serialVersionUID = -8101741014979144426L;
+ private static final long serialVersionUID = 1;
String name;
String nodepoolId;
@@ -58,11 +61,41 @@ public class RmQueriedMachine
shares.add(rqs);
}
+ /**
+ * @return the name of the machine.
+ */
public String getId() { return name; }
+
+ /**
+ * @return the amount of RAM in the machine, in kilobytes.
+ */
public long getMemory() { return memory; }
+
+ /**
+ * @return the number of quantum shares supported by the machine. For example, if the share quantum is
+ * 15GB, a 48GB machine is of order 3.
+ */
public int getShareOrder() { return order; }
+
+ /**
+ * @return whether the host contains blacklisted processes. A blacklisted process is one whose characteristics
+ * no longer match the machine. For example, after reconfiguration, this may be an illegal assignemnt
+ * for the request. Until such time as the request is (externally) removed, the RM has to account for
+ * the space by maintaining records on the blacklisted work. If a machine is blacklisted, it is not
+ * schedulable for new work.
+ */
public boolean isBlacklisted() { return blacklisted; } // UIMA-4142
+
+ /**
+ * @return true if the machine is varied online and false otherwise. Note that a machine might "not varied offline",
+ * but not responsive (not sending heartbeats).
+ */
public boolean isOnline() { return online; } // UIMA-4142
+
+ /**
+ * @return true if the machine is sending heartbeats. Note that a machine might be sending heartbeats but be varied
+ * offline or blacklisted, and hence not schedulable.
+ */
public boolean isResponsive() { return responsive; } // UIMA-4142
public String toString()
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedNodepool.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedNodepool.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedNodepool.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedNodepool.java Fri Apr 17 18:39:51 2015
@@ -21,6 +21,15 @@ package org.apache.uima.ducc.common.admi
import java.io.Serializable;
import java.util.Arrays;
+/**
+ * This class returns details about the current state of each nodepool.
+ *
+ * Regarding the <code>getFreeMachines</code> and <code>getVirtualMachines</code> calls, these
+ * two arrays together show the available memory that is free and schedulable. For example, if
+ * a 48GB machine has a 15GB process scheduled on it (assuming a share quantum of 15GB), the
+ * response will show one 30GB virtual machine, and the expected count of 48GB machines will be
+ * reduced by one.
+ */
public class RmQueriedNodepool
implements Serializable
{
@@ -37,11 +46,17 @@ public class RmQueriedNodepool
private int[] freeMachines;
private int[] virtualMachines;
+ /**
+ * Used by RM only.
+ */
public RmQueriedNodepool()
{
}
+ /**
+ * @return the name of the nodepool
+ */
public String getName() {
return name;
}
@@ -50,6 +65,9 @@ public class RmQueriedNodepool
this.name = name;
}
+ /**
+ * @return the number of online, schedulable hosts in the nodepool.
+ */
public int getOnline() {
return online;
}
@@ -58,6 +76,9 @@ public class RmQueriedNodepool
this.online = online;
}
+ /**
+ * @return the number of hosts which once were responding but have stopped sending heartbeats.
+ */
public int getDead() {
return dead;
}
@@ -66,6 +87,9 @@ public class RmQueriedNodepool
this.dead = dead;
}
+ /**
+ * @return the number of hosts which are varied offline.
+ */
public int getOffline() {
return offline;
}
@@ -74,6 +98,9 @@ public class RmQueriedNodepool
this.offline = offline;
}
+ /**
+ * @return the total number of schedulable quantum shares in the nodepool.
+ */
public int getSharesAvailable() {
return sharesAvailable;
}
@@ -82,6 +109,9 @@ public class RmQueriedNodepool
this.sharesAvailable = sharesAvailable;
}
+ /**
+ * @return the number of unused quantum shares in the nodepool.
+ */
public int getSharesFree() {
return sharesFree;
}
@@ -90,6 +120,10 @@ public class RmQueriedNodepool
this.sharesFree = sharesFree;
}
+ /**
+ * @return an array, indexed by multiples of the share quantum, showing the total number of machines
+ * known to the nodepool, regardless of status, whose memory capacity matches that multiple of the quantum.
+ */
public int[] getAllMachines() {
return allMachines;
}
@@ -98,6 +132,10 @@ public class RmQueriedNodepool
this.allMachines = allMachines;
}
+ /**
+ * @return an array, indexed by multiples of the share quantum, showing the total number of machines
+ * which are online and schedulable whose memory capacity matches that multiple of the quantum.
+ */
public int[] getOnlineMachines() {
return onlineMachines;
}
@@ -106,6 +144,10 @@ public class RmQueriedNodepool
this.onlineMachines = onlineMachines;
}
+ /**
+ * @return an array, indexed by multiples of the share quantum, showing the total number of physical
+ * machines which have nothing scheduled on them.
+ */
public int[] getFreeMachines() {
return freeMachines;
}
@@ -114,6 +156,10 @@ public class RmQueriedNodepool
this.freeMachines = freeMachines;
}
+ /**
+ * @return an array, indexed by multiples of the share quantum, showing the total number of
+ * shares free on machines that to have something scheduled on them.
+ */
public int[] getVirtualMachines() {
return virtualMachines;
}
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedShare.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedShare.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedShare.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/admin/event/RmQueriedShare.java Fri Apr 17 18:39:51 2015
@@ -20,6 +20,9 @@ package org.apache.uima.ducc.common.admi
import java.io.Serializable;
+/**
+ * This object returns details about every unit of scheduled work in the sysmte.
+ */
public class RmQueriedShare
implements Serializable
{
@@ -53,15 +56,65 @@ public class RmQueriedShare
public void setInitialized(boolean v) { this.initialized = v; }
public void setBlacklisted() { this.blacklisted = true; }
+ /**
+ * @return the numeric ID of the request, as assigned by the Orchestrator. Note that many
+ * shares may have the same job id, if the work is scaled-out in thecluster.
+ */
public long getJobId() { return this.jobId; }
+
+ /**
+ * @return the unique ID of the scheduled work, as assigned by the RM. If a job is scaled out,
+ * its processes will have the same JobId, but a different share ID as returned by this method.
+ */
public long getId() { return this.shareId; }
+
+ /**
+ * @return the initialization investment, in millliseconds. This is the amount of time spent thus far
+ * by the processes in its initialization phase.
+ */
public long getInvestmentInit() { return this.investmentInit; }
+
+ /**
+ * @return the runtime investment, in milliseconds. This is the sum of the time spent by each thread
+ * in the processes, <em>on its current CAS</em>. When the work represented by a CAS is
+ * completed, the thread contributes nothing to the investment until (or unless) it starts
+ * the process a new CAS. The runtime investment is a heuristic used by the RM to determine
+ * which processes would lose the least amount of work if it was preempted.
+ *
+ * Note that as of DUCC 2.0.0, a thread may request a reset of its investment, e.g. after
+ * it has checkpointed, allowing for very long-running CASs while still providing an accurate
+ * reflection of its investment.
+ */
public long getInvestmentRt() { return this.investmentRt; }
+
+ /**
+ * @return the share-order of the processes. This is the number of quantum shares occupied by each
+ * processes in the job. For example, if the quantum is 15GB a 45GB process is an <em>order 3</em>
+ * process.
+ */
public int getShareOrder() { return order; }
+ /**
+ * @return true if the process has been preempted but the Orchestrator has not yet acknowledged that the
+ * process has exited, and false otherwise.
+ */
public boolean isEvicted() { return evicted; }
+
+ /**
+ * @return true if the host the processes is running on has stopped responding, the RM has send a purge order
+ * to the Orchestrator, but has not yet received confirmation that the processes has exited, and false
+ * otherwise.
+ */
public boolean isPurged() { return purged; }
+
+ /**
+ * @return true of the process is non-preemptable, and true otherwise.
+ */
public boolean isFixed() { return fixed; }
+
+ /**
+ * @return true if the process has completed its initialization phase, and false otherwise.
+ */
public boolean isInitialized() { return initialized; }
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/main/DuccRmAdmin.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/main/DuccRmAdmin.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/main/DuccRmAdmin.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-common/src/main/java/org/apache/uima/ducc/common/main/DuccRmAdmin.java Fri Apr 17 18:39:51 2015
@@ -47,6 +47,21 @@ import org.apache.uima.ducc.common.utils
import com.thoughtworks.xstream.XStream;
+/**
+ * This class provides the API and CLI to the Resource Managager administrative functions.
+ *
+ * The functions provided by this class are exposed both to Java programs, and scripting.
+ *
+ * When invoked through the <code>main</code> class, the specified funtions emit a string which is
+ * easily parsable by scripting. Specifically, the qoccupancy and qload interfaces return a
+ * string that can be converted to List and Dictionary objects in Python via Python's
+ * <code>eval</code> function.
+ *
+ * When invokded via Java the response is returned in Java objects, as described below.
+ * The use of this class's Java API is intended for DUCC System programming, and requires
+ * the Camel, Spring, ActiveMQ, and Log4j classes in the classpath, as well as the DUCC
+ * Transport and Common jars.
+ */
public class DuccRmAdmin
extends AbstractDuccComponent
{
@@ -60,6 +75,14 @@ public class DuccRmAdmin
String user;
byte[] cypheredMessage;
+ /**
+ * Creates a new instance of the RM administrative interface.
+
+ * @param context This is the Camel context to use. Usually it is sufficient to simply provide
+ * <code>new DefaultCamelContext()</code>.
+ * @param epname This is the RM JMS endpoint as configured in ducc.properties. Usually it is
+ * sufficient to provide <code>ducc.rm.admin.endpoint</code>.
+ */
public DuccRmAdmin(CamelContext context, String epname)
{
super("DuccServiceReaper", context);
@@ -117,11 +140,17 @@ public class DuccRmAdmin
}
}
+ /**
+ * This provides direct access to the logger for the class.
+ */
public DuccLogger getLogger()
{
return new DuccLogger("Admin");
}
+ /**
+ * Turn the request int xstream format for transmission to RM.
+ */
private String marshallEvent(DuccAdminEvent duccEvent)
throws Exception
{
@@ -130,24 +159,17 @@ public class DuccRmAdmin
return xStream.toXML(duccEvent);
}
- // private RmAdminReply unmarshallEvent(Object targetToUnmarshall)
- // throws Exception
- // {
- // XStream xStream = new XStream(new DomDriver());
- // String claz = targetToUnmarshall.getClass().getName();
-
- // if (targetToUnmarshall instanceof byte[]) {
- // Object reply = xStream.fromXML(new String((byte[]) targetToUnmarshall));
- // if (reply instanceof RmAdminReply) {
- // return (RmAdminReply) reply;
- // } else {
- // claz = (reply == null) ? "NULL" : reply.getClass().getName();
- // }
- // }
- // throw new Exception( "Unexpected Reply type received from Ducc Component. Expected DuccEvent, instead received: " + claz);
- // }
-
- public RmAdminReply dispatchAndWaitForReply(DuccAdminEvent duccEvent)
+ /**
+ * Marshall and transmit the request to RM, waiting for the response.
+ *
+ * @param A DuccAdminEvent appropriate to the desired function.
+ *
+ * @return An {@link RmAdminReply RmAdminReply} appropriate to the response. See the specific replies
+ * for details.
+
+ * @throws Exception if anything goes wrong in transmission or receipt of the request.
+ */
+ private RmAdminReply dispatchAndWaitForReply(DuccAdminEvent duccEvent)
throws Exception
{
int maxRetryCount = 20;
@@ -188,41 +210,55 @@ public class DuccRmAdmin
}
/**
- * Interprets and executes Admin command
+ * This causes the RM to "vary off" a set of hosts. The hosts may continue to broadcast state, and
+ * RM trackes their online/offline status, but it stops scheduling to them. If there is evictable work
+ * on the hosts, RM will send eviction orders to the Orchestrator in order to clear them.
+ *
+ * @param args This is an array of hostnames indicating the hosts to be varied offline.
*
- * @throws Exception
+ * @return A generic {@link RmAdminReply RmAdminReply} indicating the result of the action.
+ *
+ * @throws Exception if anything goes wrong in transmission or receipt of the request.
*/
- public void varyoff(String[] args)
+ public RmAdminReply varyoff(String[] args)
throws Exception
{
String[] nodes = new String[args.length - 1];
for ( int i = 1; i < args.length; i++) nodes[i-1] = args[i]; // take a slice of the array
RmAdminVaryOff vo = new RmAdminVaryOff(nodes, user, cypheredMessage);
- RmAdminReply reply = dispatchAndWaitForReply(vo);
- System.out.println(reply.getResponse());
+ return dispatchAndWaitForReply(vo);
}
/**
- * Interprets and executes Admin command
+ * This causes the RM to "vary on" a set of hosts. If the hosts are broadcasting state,
+ * they are immediately available for scheduling. This commnd does not start the DUCC agents,
+ * it only instructs RM that, if the hosts was previously offline, it should now be used for
+ * scheduling if and when the host is responding and sending heartbeats.
+ *
+ * @param args This is an array of hostnames indicating the hosts to be varied nline.
*
- * @throws Exception
+ * @return A generic {@link RmAdminReply RmAdminReply} indicating the result of the action.
+ *
+ * @throws Exception if anything goes wrong in transmission or receipt of the request.
*/
- public void varyon(String[] args)
+ public RmAdminReply varyon(String[] args)
throws Exception
{
String[] nodes = new String[args.length - 1];
for ( int i = 1; i < args.length; i++) nodes[i-1] = args[i]; // take a slice of the array
RmAdminVaryOn vo = new RmAdminVaryOn(nodes, user, cypheredMessage);
- RmAdminReply reply = dispatchAndWaitForReply(vo);
- System.out.println(reply.getResponse());
+ return dispatchAndWaitForReply(vo);
}
/**
- * Query load.
+ * This queries the current workload demand and resource supply in RM.
+ *
+ * @return A {@link RmAdminQLoadReply RmAdminQLoadReply} containing data regarding the current
+ * class and nodepool state.
*
- * @throws Exception
+ * @throws Exception if anything goes wrong in transmission or receipt of the request.
*/
public RmAdminQLoadReply qload()
throws Exception
@@ -232,9 +268,12 @@ public class DuccRmAdmin
}
/**
- * Query occupancy.
+ * This queries details on each host the RM is schedling to.
+ *
+ * @return A {@link RmAdminQOccupancyReply RmAdminQOccupancyReply} containing data regarding the current
+ * hosts.
*
- * @throws Exception
+ * @throws Exception if anything goes wrong in transmission or receipt of the request.
*/
public RmAdminQOccupancyReply qoccupancy()
throws Exception
@@ -243,21 +282,31 @@ public class DuccRmAdmin
return (RmAdminQOccupancyReply) dispatchAndWaitForReply(qo);
}
+ // UIMA-4142
/**
- * Send reconfigure event to RM.
- * UIMA-4142
+ * Send a reconfigure event to RM. RM rereads all its configuration data an possibly reconfigures
+ * the schedule if needed.
+ *
+ * @return {@link RmAdminReply RmAdminReply}. The message must be <code>Reconfiguration complete.</code>;
+ * any other response indicates failure. Failure occurs when the new configuration is invalid. If this
+ * occurs use <code>check_ducc -cv </code> to read and validate the current configuration.
*
- * @throws Exception
+ * @throws Exception if anything goes wrong in transmission or receipt of the request.
*/
- public void reconfigure()
+ public RmAdminReply reconfigure()
throws Exception
{
RmAdminReconfigure np = new RmAdminReconfigure(user, cypheredMessage);
- RmAdminReply reply = dispatchAndWaitForReply(np);
- System.out.println(reply.getResponse());
+ return dispatchAndWaitForReply(np);
}
-
+ /**
+ * This is called from <code>main</code> in response to a CLI request.
+ *
+ * @param args the command line arguments. See the usage method below for details.
+ *
+ * @throws Exception if anything goes wrong in transmission or receipt of the request.
+ */
public void run(String[] args)
throws Exception
{
@@ -268,18 +317,19 @@ public class DuccRmAdmin
if ( args[0].equals("--varyoff")) {
if ( args.length < 2 ) usage("Missing node list");
- varyoff(args);
+ RmAdminReply reply = varyoff(args);
+ System.out.println(reply.getResponse());
return;
}
if ( args[0].equals("--varyon")) {
if ( args.length < 2 ) usage("Missing node list");
- varyon(args);
+ RmAdminReply reply = varyon(args);
+ System.out.println(reply.getResponse());
return;
}
if ( args[0].equals("--qload")) {
-
RmAdminQLoadReply ret = qload();
System.out.println(ret.toString());
return;
@@ -293,14 +343,15 @@ public class DuccRmAdmin
if ( args[0].equals("--reconfigure") ) { // UIMA-4142
if ( args.length != 1 ) usage("Reconfigure takes no arguments.");
- reconfigure();
+ RmAdminReply reply = reconfigure();
+ System.out.println(reply.getResponse());
return;
}
System.out.println("Unknown command: " + args[0]);
}
- public static void usage(String msg)
+ private static void usage(String msg)
{
if ( msg != null ) System.out.println(msg);
@@ -316,6 +367,9 @@ public class DuccRmAdmin
System.exit(1);
}
+ /**
+ * This is provided for use by the CLI, to invoke the varioius RM administrative commands.
+ */
public static void main(String[] args)
{
try {
Modified: uima/sandbox/uima-ducc/trunk/uima-ducc-rm/src/main/java/org/apache/uima/ducc/rm/scheduler/Scheduler.java
URL: http://svn.apache.org/viewvc/uima/sandbox/uima-ducc/trunk/uima-ducc-rm/src/main/java/org/apache/uima/ducc/rm/scheduler/Scheduler.java?rev=1674377&r1=1674376&r2=1674377&view=diff
==============================================================================
--- uima/sandbox/uima-ducc/trunk/uima-ducc-rm/src/main/java/org/apache/uima/ducc/rm/scheduler/Scheduler.java (original)
+++ uima/sandbox/uima-ducc/trunk/uima-ducc-rm/src/main/java/org/apache/uima/ducc/rm/scheduler/Scheduler.java Fri Apr 17 18:39:51 2015
@@ -1155,7 +1155,7 @@ public class Scheduler
n = resolve(n);
if ( n == null ) {
- reply.append("VaryOn: The node cannot be found in the RM.\n");
+ reply.append("VaryOn: " + n + " cannot be found in the RM.\n");
} else {
NodePool np = nodepoolsByNode.get(n); // if null, resolve will fail
String repl = np.varyon(n);
@@ -1175,7 +1175,7 @@ public class Scheduler
n = resolve(n);
if ( n == null ) {
- reply.append("VaryOff: The node cannot be found in the RM.\n");
+ reply.append("VaryOff: " + n + " cannot be found in the RM.\n");
} else {
NodePool np = nodepoolsByNode.get(n); // if null, resolve will fail
String repl = np.varyoff(n);