You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mesos.apache.org by vi...@apache.org on 2014/04/02 06:56:50 UTC
git commit: Improved Javadoc (use @param, @return, etc).
Repository: mesos
Updated Branches:
refs/heads/master 3da7e6863 -> 058599b0a
Improved Javadoc (use @param, @return, etc).
Review: https://reviews.apache.org/r/19859
Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/058599b0
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/058599b0
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/058599b0
Branch: refs/heads/master
Commit: 058599b0ac4511ffccae4c254b81fad949e65499
Parents: 3da7e68
Author: Tobi Knaup <to...@knaup.me>
Authored: Tue Apr 1 21:55:48 2014 -0700
Committer: Vinod Kone <vi...@twitter.com>
Committed: Tue Apr 1 21:55:48 2014 -0700
----------------------------------------------------------------------
src/java/src/org/apache/mesos/Executor.java | 24 +++++++++
.../src/org/apache/mesos/ExecutorDriver.java | 16 ++++++
src/java/src/org/apache/mesos/Scheduler.java | 37 ++++++++++++-
.../src/org/apache/mesos/SchedulerDriver.java | 56 +++++++++++++++++++-
src/java/src/org/apache/mesos/state/State.java | 12 +++++
.../src/org/apache/mesos/state/Variable.java | 10 ++++
.../org/apache/mesos/state/ZooKeeperState.java | 2 +-
7 files changed, 153 insertions(+), 4 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/mesos/blob/058599b0/src/java/src/org/apache/mesos/Executor.java
----------------------------------------------------------------------
diff --git a/src/java/src/org/apache/mesos/Executor.java b/src/java/src/org/apache/mesos/Executor.java
index 8f4eaee..cacb4e9 100644
--- a/src/java/src/org/apache/mesos/Executor.java
+++ b/src/java/src/org/apache/mesos/Executor.java
@@ -41,6 +41,11 @@ public interface Executor {
* data to it's executors through the {@link ExecutorInfo#data}
* field. TODO(vinod): Add a new reregistered callback for when the executor
* re-connects with a restarted slave.
+ *
+ * @param driver The driver that was used to start this executor.
+ * @param executorInfo The executor info that was used to start this executor.
+ * @param frameworkInfo The framework that started this executor.
+ * @param slaveInfo The slave this executor is registered with.
*/
void registered(ExecutorDriver driver,
ExecutorInfo executorInfo,
@@ -49,12 +54,17 @@ public interface Executor {
/**
* Invoked when the executor re-registers with a restarted slave.
+ *
+ * @param driver The driver that was used to start this executor.
+ * @param slaveInfo The slave this executor re-registered with.
*/
void reregistered(ExecutorDriver driver, SlaveInfo slaveInfo);
/**
* Invoked when the executor becomes "disconnected" from the slave
* (e.g., the slave is being restarted due to an upgrade).
+ *
+ * @param driver The driver that was used to start this executor.
*/
void disconnected(ExecutorDriver driver);
@@ -64,6 +74,9 @@ public interface Executor {
* realized with a thread, a process, or some simple computation,
* however, no other callbacks will be invoked on this executor
* until this callback has returned.
+ *
+ * @param driver The driver that was used to start this executor.
+ * @param task The info about the task that was launched.
*/
void launchTask(ExecutorDriver driver, TaskInfo task);
@@ -74,6 +87,9 @@ public interface Executor {
* responsible for creating a new TaskStatus (i.e., with
* TASK_KILLED) and invoking {@link
* ExecutorDriver#sendStatusUpdate}.
+ *
+ * @param driver The driver that was used to start this executor.
+ * @param taskId The ID of the task that was killed.
*/
void killTask(ExecutorDriver driver, TaskID taskId);
@@ -81,6 +97,9 @@ public interface Executor {
* Invoked when a framework message has arrived for this
* executor. These messages are best effort; do not expect a
* framework message to be retransmitted in any reliable fashion.
+ *
+ * @param driver The driver that was used to start this executor.
+ * @param data The message data.
*/
void frameworkMessage(ExecutorDriver driver, byte[] data);
@@ -90,6 +109,8 @@ public interface Executor {
* executor has terminated any tasks that the executor did not send
* terminal status updates for (e.g., TASK_KILLED, TASK_FINISHED,
* TASK_FAILED, etc) a TASK_LOST status update will be created.
+ *
+ * @param driver The driver that was used to start this executor.
*/
void shutdown(ExecutorDriver driver);
@@ -97,6 +118,9 @@ public interface Executor {
* Invoked when a fatal error has occured with the executor and/or
* executor driver. The driver will be aborted BEFORE invoking this
* callback.
+ *
+ * @param driver The driver that was used to start this executor.
+ * @param message The error message.
*/
void error(ExecutorDriver driver, String message);
}
http://git-wip-us.apache.org/repos/asf/mesos/blob/058599b0/src/java/src/org/apache/mesos/ExecutorDriver.java
----------------------------------------------------------------------
diff --git a/src/java/src/org/apache/mesos/ExecutorDriver.java b/src/java/src/org/apache/mesos/ExecutorDriver.java
index cb14f38..56345df 100644
--- a/src/java/src/org/apache/mesos/ExecutorDriver.java
+++ b/src/java/src/org/apache/mesos/ExecutorDriver.java
@@ -31,11 +31,15 @@ public interface ExecutorDriver {
/**
* Starts the executor driver. This needs to be called before any
* other driver calls are made.
+ *
+ * @return The state of the driver after the call.
*/
public Status start();
/**
* Stops the executor driver.
+ *
+ * @return The state of the driver after the call.
*/
public Status stop();
@@ -47,6 +51,8 @@ public interface ExecutorDriver {
* and instantiate and start another driver if desired (from within
* the same process ... although this functionality is currently not
* supported for executors).
+ *
+ * @return The state of the driver after the call.
*/
public Status abort();
@@ -55,11 +61,15 @@ public interface ExecutorDriver {
* _blocking_ the current thread indefinitely. The return status of
* this function can be used to determine if the driver was aborted
* (see mesos.proto for a description of Status).
+ *
+ * @return The state of the driver after the call.
*/
public Status join();
/**
* Starts and immediately joins (i.e., blocks on) the driver.
+ *
+ * @return The state of the driver after the call.
*/
public Status run();
@@ -69,6 +79,9 @@ public interface ExecutorDriver {
* executor is terminated (in which case, a TASK_LOST status update
* will be sent). See {@link Scheduler#statusUpdate} for more
* information about status update acknowledgements.
+ *
+ * @param status The status update to send.
+ * @return The state of the driver after the call.
*/
public Status sendStatusUpdate(TaskStatus status);
@@ -76,6 +89,9 @@ public interface ExecutorDriver {
* Sends a message to the framework scheduler. These messages are
* best effort; do not expect a framework message to be
* retransmitted in any reliable fashion.
+ *
+ * @param data The message data.
+ * @return The state of the driver after the call.
*/
public Status sendFrameworkMessage(byte[] data);
}
http://git-wip-us.apache.org/repos/asf/mesos/blob/058599b0/src/java/src/org/apache/mesos/Scheduler.java
----------------------------------------------------------------------
diff --git a/src/java/src/org/apache/mesos/Scheduler.java b/src/java/src/org/apache/mesos/Scheduler.java
index 55c4706..3043f60 100644
--- a/src/java/src/org/apache/mesos/Scheduler.java
+++ b/src/java/src/org/apache/mesos/Scheduler.java
@@ -43,6 +43,10 @@ public interface Scheduler {
* master. A unique ID (generated by the master) used for
* distinguishing this framework from others and MasterInfo
* with the ip and port of the current master are provided as arguments.
+ *
+ * @param driver The scheduler driver that was used to run this scheduler.
+ * @param frameworkId The framework ID generated by the master.
+ * @param masterInfo Info about the current master, including ip and port.
*/
void registered(SchedulerDriver driver,
FrameworkID frameworkId,
@@ -53,6 +57,9 @@ public interface Scheduler {
* This is only called when the scheduler has previously been registered.
* MasterInfo containing the updated information about the elected master
* is provided as an argument.
+ *
+ * @param driver The driver that was used to run this scheduler.
+ * @param masterInfo The updated information about the elected master.
*/
void reregistered(SchedulerDriver driver, MasterInfo masterInfo);
@@ -70,6 +77,9 @@ public interface Scheduler {
* will have those resources rescinded (or if a framework has
* already launched tasks with those resources then those tasks will
* fail with a TASK_LOST status and a message saying as much).
+ *
+ * @param driver The driver that was used to run this scheduler.
+ * @param offers The resources offered to this framework.
*/
void resourceOffers(SchedulerDriver driver, List<Offer> offers);
@@ -80,6 +90,9 @@ public interface Scheduler {
* message, failing over framework, etc.), a framwork that attempts
* to launch tasks using an invalid offer will receive TASK_LOST
* status updats for those tasks (see {@link #resourceOffers}).
+ *
+ * @param driver The driver that was used to run this scheduler.
+ * @param offerId The ID of the offer that was rescinded.
*/
void offerRescinded(SchedulerDriver driver, OfferID offerId);
@@ -92,6 +105,9 @@ public interface Scheduler {
* the process exits) another status update will be delivered (note,
* however, that this is currently not true if the slave sending the
* status update is lost/fails during that time).
+ *
+ * @param driver The driver that was used to run this scheduler.
+ * @param status The status update, which includes the task ID and status.
*/
void statusUpdate(SchedulerDriver driver, TaskStatus status);
@@ -99,6 +115,11 @@ public interface Scheduler {
* Invoked when an executor sends a message. These messages are best
* effort; do not expect a framework message to be retransmitted in
* any reliable fashion.
+ *
+ * @param driver The driver that was used to run this scheduler.
+ * @param executorId The ID of the executor that sent the message.
+ * @param slaveId The ID of the slave that launched the executor.
+ * @param data The message payload.
*/
void frameworkMessage(SchedulerDriver driver,
ExecutorID executorId,
@@ -108,6 +129,8 @@ public interface Scheduler {
/**
* Invoked when the scheduler becomes "disconnected" from the master
* (e.g., the master fails and another is taking over).
+ *
+ * @param driver The driver that was used to run this scheduler.
*/
void disconnected(SchedulerDriver driver);
@@ -115,6 +138,9 @@ public interface Scheduler {
* Invoked when a slave has been determined unreachable (e.g.,
* machine failure, network partition). Most frameworks will need to
* reschedule any tasks launched on this slave on a new slave.
+ *
+ * @param driver The driver that was used to run this scheduler.
+ * @param slaveId The ID of the slave that was lost.
*/
void slaveLost(SchedulerDriver driver, SlaveID slaveId);
@@ -122,6 +148,11 @@ public interface Scheduler {
* Invoked when an executor has exited/terminated. Note that any
* tasks running will have TASK_LOST status updates automagically
* generated.
+ *
+ * @param driver The driver that was used to run this scheduler.
+ * @param executorId The ID of the executor that was lost.
+ * @param slaveId The ID of the slave that launched the executor.
+ * @param status The exit status of the executor.
*/
void executorLost(SchedulerDriver driver,
ExecutorID executorId,
@@ -130,8 +161,10 @@ public interface Scheduler {
/**
* Invoked when there is an unrecoverable error in the scheduler or
- * scheduler driver. The driver will be aborted BEFORE invoking this
- * callback.
+ * driver. The driver will be aborted BEFORE invoking this callback.
+ *
+ * @param driver The driver that was used to run this scheduler.
+ * @param message The error message.
*/
void error(SchedulerDriver driver, String message);
}
http://git-wip-us.apache.org/repos/asf/mesos/blob/058599b0/src/java/src/org/apache/mesos/SchedulerDriver.java
----------------------------------------------------------------------
diff --git a/src/java/src/org/apache/mesos/SchedulerDriver.java b/src/java/src/org/apache/mesos/SchedulerDriver.java
index 6bca879..ae2d915 100644
--- a/src/java/src/org/apache/mesos/SchedulerDriver.java
+++ b/src/java/src/org/apache/mesos/SchedulerDriver.java
@@ -34,6 +34,8 @@ public interface SchedulerDriver {
/**
* Starts the scheduler driver. This needs to be called before any
* other driver calls are made.
+ *
+ * @return The state of the driver after the call.
*/
Status start();
@@ -45,11 +47,16 @@ public interface SchedulerDriver {
* running (for some master specified failover timeout) allowing the
* scheduler to reconnect (possibly in the same process, or from a
* different process, for example, on a different machine).
+ *
+ * @param failover Whether framework failover is expected.
+ * @return The state of the driver after the call.
*/
Status stop(boolean failover);
/**
* Stops the scheduler driver assuming no failover.
+ *
+ * @return The state of the driver after the call.
*/
Status stop();
@@ -60,6 +67,8 @@ public interface SchedulerDriver {
* the return status of {@link #join}, see below), and instantiate
* and start another driver if desired (from within the same
* process).
+ *
+ * @return The state of the driver after the call.
*/
Status abort();
@@ -68,11 +77,15 @@ public interface SchedulerDriver {
* _blocking_ the current thread indefinitely. The return status of
* this function can be used to determine if the driver was aborted
* (see mesos.proto for a description of Status).
+ *
+ * @return The state of the driver after the call.
*/
Status join();
/**
* Starts and immediately joins (i.e., blocks on) the driver.
+ *
+ * @return The state of the driver after the call.
*/
Status run();
@@ -82,6 +95,9 @@ public interface SchedulerDriver {
* from specific slaves). Any resources available are offered to the
* framework via {@link Scheduler#resourceOffers} callback,
* asynchronously.
+ *
+ * @param requests The resource requests.
+ * @return The state of the driver after the call.
*/
Status requestResources(Collection<Request> requests);
@@ -93,7 +109,12 @@ public interface SchedulerDriver {
* be considered declined. The specified filters are applied on all
* unused resources (see mesos.proto for a description of Filters).
* Invoking this function with an empty collection of tasks declines
- * offers in their entirety (see {@link #declineOffer}.
+ * offers in their entirety (see {@link #declineOffer}).
+ *
+ * @param offerIds The collection of offer IDs.
+ * @param tasks The collection of tasks to be launched.
+ * @param filters The filters to set for any remaining resources.
+ * @return The state of the driver after the call.
*/
Status launchTasks(Collection<OfferID> offerIds,
Collection<TaskInfo> tasks,
@@ -101,6 +122,10 @@ public interface SchedulerDriver {
/**
* Launches the given set of tasks. See above for details.
+ *
+ * @param offerIds The collection of offer IDs.
+ * @param tasks The collection of tasks to be launched.
+ * @return The state of the driver after the call.
*/
Status launchTasks(Collection<OfferID> offerIds, Collection<TaskInfo> tasks);
@@ -109,6 +134,11 @@ public interface SchedulerDriver {
* Collection<OfferID> offerId,
* Collection<TaskInfo> tasks,
* Filters filters) instead.
+ *
+ * @param offerId The offer ID.
+ * @param tasks The collection of tasks to be launched.
+ * @param filters The filters to set for any remaining resources.
+ * @return The state of the driver after the call.
*/
Status launchTasks(OfferID offerId,
Collection<TaskInfo> tasks,
@@ -118,6 +148,10 @@ public interface SchedulerDriver {
* @deprecated Use launchTasks(
* Collection<OfferID> offerId,
* Collection<TaskInfo> tasks) instead.
+ *
+ * @param offerId The offer ID.
+ * @param tasks The collection of tasks to be launched.
+ * @return The state of the driver after the call.
*/
Status launchTasks(OfferID offerId, Collection<TaskInfo> tasks);
@@ -127,6 +161,9 @@ public interface SchedulerDriver {
* while it was attempting to kill a task it will need to retry in
* the future Likewise, if unregistered / disconnected, the request
* will be dropped (these semantics may be changed in the future).
+ *
+ * @param taskId The ID of the task to be killed.
+ * @return The state of the driver after the call.
*/
Status killTask(TaskID taskId);
@@ -136,11 +173,18 @@ public interface SchedulerDriver {
* Filters). Note that this can be done at any time, it is not
* necessary to do this within the {@link Scheduler#resourceOffers}
* callback.
+ *
+ * @param offerId The ID of the offer to be declined.
+ * @param filters The filters to set for any remaining resources.
+ * @return The state of the driver after the call.
*/
Status declineOffer(OfferID offerId, Filters filters);
/**
* Declines an offer in its entirety. See above for details.
+ *
+ * @param offerId The ID of the offer to be declined.
+ * @return The state of the driver after the call.
*/
Status declineOffer(OfferID offerId);
@@ -148,6 +192,8 @@ public interface SchedulerDriver {
* Removes all filters, previously set by the framework (via {@link
* #launchTasks}). This enables the framework to receive offers
* from those filtered slaves.
+ *
+ * @return The state of the driver after the call.
*/
Status reviveOffers();
@@ -155,6 +201,11 @@ public interface SchedulerDriver {
* Sends a message from the framework to one of its executors. These
* messages are best effort; do not expect a framework message to be
* retransmitted in any reliable fashion.
+ *
+ * @param executorId The ID of the executor to send the message to.
+ * @param slaveId The ID of the slave that is running the executor.
+ * @param data The message.
+ * @return The state of the driver after the call.
*/
Status sendFrameworkMessage(ExecutorID executorId,
SlaveID slaveId,
@@ -163,6 +214,9 @@ public interface SchedulerDriver {
/**
* Reconciliation of tasks causes the master to send status updates for tasks
* whose status differs from the status sent here.
+ *
+ * @param statuses The collection of tasks and statuses to reconcile.
+ * @return The state of the driver after the call.
*/
Status reconcileTasks(Collection<TaskStatus> statuses);
}
http://git-wip-us.apache.org/repos/asf/mesos/blob/058599b0/src/java/src/org/apache/mesos/state/State.java
----------------------------------------------------------------------
diff --git a/src/java/src/org/apache/mesos/state/State.java b/src/java/src/org/apache/mesos/state/State.java
index dccb0ff..d14d79b 100644
--- a/src/java/src/org/apache/mesos/state/State.java
+++ b/src/java/src/org/apache/mesos/state/State.java
@@ -48,6 +48,9 @@ public interface State {
/**
* Returns an immutable "variable" representing the current value
* from the state associated with the specified name.
+ *
+ * @param name The name of the variable.
+ * @return A future of the variable.
*/
Future<Variable> fetch(String name);
@@ -55,17 +58,26 @@ public interface State {
* Returns an immutable "variable" representing the current value in
* the state if updating the specified variable in the state was
* successful, otherwise returns null.
+ *
+ * @param variable The variable to be stored.
+ * @return A future of a variable with the new value on success,
+ * or null on failure.
*/
Future<Variable> store(Variable variable);
/**
* Returns true if successfully expunged the variable from the state
* or false if the variable did not exist or was no longer valid.
+ *
+ * @param variable The variable to be expunged.
+ * @return A future of true on success, false on failure.
*/
Future<Boolean> expunge(Variable variable);
/**
* Returns an iterator of variable names in the state.
+ *
+ * @return A future of an iterator over all variable names in the state.
*/
Future<Iterator<String>> names();
}
http://git-wip-us.apache.org/repos/asf/mesos/blob/058599b0/src/java/src/org/apache/mesos/state/Variable.java
----------------------------------------------------------------------
diff --git a/src/java/src/org/apache/mesos/state/Variable.java b/src/java/src/org/apache/mesos/state/Variable.java
index bedb74b..8e1ca69 100644
--- a/src/java/src/org/apache/mesos/state/Variable.java
+++ b/src/java/src/org/apache/mesos/state/Variable.java
@@ -18,16 +18,26 @@
package org.apache.mesos.state;
+/**
+ * Represents a key/value pair stored in the {@link State}. Variables
+ * are versioned such that setting a variable in the state will only
+ * succeed if the variable has not changed since last fetched.
+ */
public class Variable {
protected Variable() {}
/**
* Returns the current value of this variable.
+ *
+ * @return The current value.
*/
public native byte[] value();
/**
* Updates the current value of this variable.
+ *
+ * @param value The new value.
+ * @return A variable representing the new value.
*/
public native Variable mutate(byte[] value);
http://git-wip-us.apache.org/repos/asf/mesos/blob/058599b0/src/java/src/org/apache/mesos/state/ZooKeeperState.java
----------------------------------------------------------------------
diff --git a/src/java/src/org/apache/mesos/state/ZooKeeperState.java b/src/java/src/org/apache/mesos/state/ZooKeeperState.java
index f3d939f..a21a4ae 100644
--- a/src/java/src/org/apache/mesos/state/ZooKeeperState.java
+++ b/src/java/src/org/apache/mesos/state/ZooKeeperState.java
@@ -50,7 +50,7 @@ public class ZooKeeperState extends AbstractState {
* @param unit Unit for session timeout.
* @param znode Path to znode where "state" should be rooted.
* @param scheme Authentication scheme (e.g., "digest").
- * @param scheme Authentication credentials (e.g., "user:pass").
+ * @param credentials Authentication credentials (e.g., "user:pass").
*/
public ZooKeeperState(String servers,
long timeout,