You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@edgent.apache.org by dl...@apache.org on 2016/07/21 13:17:48 UTC
[47/54] [abbrv] [partial] incubator-quarks git commit: add
"org.apache." prefix to edgent package names
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/Configs.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/Configs.java b/api/execution/src/main/java/edgent/execution/Configs.java
deleted file mode 100644
index 715aef5..0000000
--- a/api/execution/src/main/java/edgent/execution/Configs.java
+++ /dev/null
@@ -1,51 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-package edgent.execution;
-
-/**
- * Configuration property names.
- *
- * Configuration is passed as a JSON collection of name/value
- * pairs when an executable is
- * {@linkplain edgent.execution.Submitter#submit(Object, com.google.gson.JsonObject) submitted}.
- * <p>
- * The configuration JSON representation is summarized in the following table:
- * </p>
- * <table border=1 cellpadding=3 cellspacing=1>
- * <caption>Summary of configuration properties</caption>
- * <tr>
- * <th align=center><b>Attribute name</b></th>
- * <th align=center><b>Type</b></th>
- * <th align=center><b>Description</b></th>
- * </tr>
- * <tr>
- * <td>{@link #JOB_NAME jobName}</td>
- * <td>String</td>
- * <td>The name of the job.</td>
- * </tr>
- * </table>
- */
-public interface Configs {
- /**
- * JOB_NAME is used to identify the submission configuration property
- * containing the job name.
- * The value is {@value}.
- */
- String JOB_NAME = "jobName";
-}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/DirectSubmitter.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/DirectSubmitter.java b/api/execution/src/main/java/edgent/execution/DirectSubmitter.java
deleted file mode 100644
index 3a8e652..0000000
--- a/api/execution/src/main/java/edgent/execution/DirectSubmitter.java
+++ /dev/null
@@ -1,44 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-package edgent.execution;
-
-import edgent.execution.services.ServiceContainer;
-
-/**
- * An interface for submission of an executable
- * that is executed directly within the current
- * virtual machine.
- *
- * @param <E> the executable type
- * @param <J> the submitted executable's future
- */
-public interface DirectSubmitter<E, J extends Job> extends Submitter<E,J> {
-
- /**
- * Access to services.
- *
- * Since any executables are executed directly within
- * the current virtual machine, callers may register
- * services that are visible to the executable
- * and its elements.
- *
- * @return Service container for this submitter.
- */
- ServiceContainer getServices();
-}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/Job.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/Job.java b/api/execution/src/main/java/edgent/execution/Job.java
deleted file mode 100644
index d90374f..0000000
--- a/api/execution/src/main/java/edgent/execution/Job.java
+++ /dev/null
@@ -1,182 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-package edgent.execution;
-
-import java.util.concurrent.ExecutionException;
-import java.util.concurrent.TimeUnit;
-import java.util.concurrent.TimeoutException;
-
-/**
- * Actions and states for execution of an Edgent job.
- *
- * The interface provides the main job lifecycle control, taking on the following
- * execution state values:
- *
- * <ul>
- * <li><b>CONSTRUCTED</b> This job has been constructed but the
- * nodes are not yet initialized.</li>
- * <li><b>INITIALIZED</b> This job has been initialized and is
- * ready to process data.
- * <li><b>RUNNING</b> This job is processing data.</li>
- * <li><b>PAUSED</b> This job is paused.</li>
- * <li><b>CLOSED</b> This job is closed.</li>
- * </ul>
- *
- * The interface provides access to two state values:
- * <ul>
- * <li> {@link #getCurrentState() Current} - The current state of execution
- * when the job is not executing a state transition; the source state
- * while the job is making a state transition after the client code
- * calls {@link #stateChange(Job.Action)}.</li>
- * <li> {@link #getNextState() Next} - The destination state while the job
- * is making a state transition; same as the current state while
- * the job state is stable (that is, not making a transition).</LI>
- * </ul>
- *
- * The interface provides access to the job nodes
- * {@linkplain #getHealth() health summary}, described by the following values:
- * <ul>
- * <li><b>HEALTHY</b> All graph nodes in the job are healthy.</li>
- * <li><b>UNHEALTHY</b> At least one graph node in the job is stopped or
- * stopping.</li>
- * </ul>
- */
-public interface Job {
- /**
- * States of a graph job.
- */
- public enum State {
- /** Initial state, the graph nodes are not yet initialized. */
- CONSTRUCTED,
- /** All the graph nodes have been initialized. */
- INITIALIZED,
- /** All the graph nodes are processing data. */
- RUNNING,
- /** All the graph nodes are paused. */
- PAUSED,
- /** All the graph nodes are closed. */
- CLOSED
- }
-
- /**
- * Enumeration for the summarized health indicator of the graph nodes.
- */
- public enum Health {
- /**
- * All graph nodes in the job are healthy.
- */
- HEALTHY,
- /**
- * The execution of at least one graph node in the job has stopped
- * because of an abnormal condition.
- */
- UNHEALTHY
- }
-
- /**
- * Actions which trigger {@link Job.State} transitions.
- */
- public enum Action {
- /** Initialize the job */
- INITIALIZE,
- /** Start the execution. */
- START,
- /** Pause the execution. */
- PAUSE,
- /** Resume the execution */
- RESUME,
- /** Close the job. */
- CLOSE
- }
-
- /**
- * Retrieves the current state of this job.
- *
- * @return the current state.
- */
- State getCurrentState();
-
- /**
- * Retrieves the next execution state when this job makes a state
- * transition.
- *
- * @return the destination state while in a state transition;
- * otherwise the same as {@link #getCurrentState()}.
- */
- State getNextState();
-
- /**
- * Initiates an execution state change.
- *
- * @param action which triggers the state change.
- * @throws IllegalArgumentException if the job is not in an appropriate
- * state for the requested action, or the action is not supported.
- */
- void stateChange(Action action) throws IllegalArgumentException;
-
- /**
- * Returns the summarized health indicator of the graph nodes.
- *
- * @return the summarized Job node health.
- */
- Health getHealth();
-
- /**
- * Returns the last error message caught by the current job execution.
- * @return the last error message or an empty string if no error has
- * been caught.
- */
- String getLastError();
-
- /**
- * Returns the name of this job. The name may be set when the job is
- * {@linkplain edgent.execution.Submitter#submit(java.lang.Object,com.google.gson.JsonObject) submitted}.
- * Implementations may create a job name if one is not specified at submit time.
- *
- * @return the job name.
- */
- String getName();
-
- /**
- * Returns the identifier of this job.
- *
- * @return this job identifier.
- */
- String getId();
-
- /**
- * Waits for any outstanding job work to complete.
- *
- * @throws ExecutionException if the job execution threw an exception.
- * @throws InterruptedException if the current thread was interrupted while waiting
- */
- void complete() throws ExecutionException, InterruptedException;
-
- /**
- * Waits for at most the specified time for the job to complete.
- *
- * @param timeout the time to wait
- * @param unit the time unit of the timeout argument
- *
- * @throws ExecutionException if the job execution threw an exception.
- * @throws InterruptedException if the current thread was interrupted while waiting
- * @throws TimeoutException if the wait timed out
- */
- void complete(long timeout, TimeUnit unit) throws ExecutionException, InterruptedException, TimeoutException;
-}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/Submitter.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/Submitter.java b/api/execution/src/main/java/edgent/execution/Submitter.java
deleted file mode 100644
index c5ee81e..0000000
--- a/api/execution/src/main/java/edgent/execution/Submitter.java
+++ /dev/null
@@ -1,56 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-package edgent.execution;
-
-import java.util.concurrent.Future;
-
-import com.google.gson.JsonObject;
-
-
-/**
- * An interface for submission of an executable.
- * <p>
- * The class implementing this interface is responsible
- * for the semantics of this operation. e.g., an direct topology
- * provider would run the topology as threads in the current jvm.
- *
- * @param <E> the executable type
- * @param <J> the submitted executable's future
- */
-public interface Submitter<E, J extends Job> {
-
- /**
- * Submit an executable.
- * No configuration options are specified,
- * this is equivalent to {@code submit(executable, new JsonObject())}.
- *
- * @param executable executable to submit
- * @return a future for the submitted executable
- */
- Future<J> submit(E executable);
-
- /**
- * Submit an executable.
- *
- * @param executable executable to submit
- * @param config context {@linkplain edgent.execution.Configs information} for the submission
- * @return a future for the submitted executable
- */
- Future<J> submit(E executable, JsonObject config);
-}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/mbeans/JobMXBean.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/mbeans/JobMXBean.java b/api/execution/src/main/java/edgent/execution/mbeans/JobMXBean.java
deleted file mode 100644
index cb1a507..0000000
--- a/api/execution/src/main/java/edgent/execution/mbeans/JobMXBean.java
+++ /dev/null
@@ -1,114 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-package edgent.execution.mbeans;
-
-
-import edgent.execution.Job;
-import edgent.execution.Job.Action;
-
-
-/**
- * Control interface for a job.
- */
-public interface JobMXBean {
- /**
- * TYPE is used to identify this bean as a job bean when building the bean's {@code ObjectName}.
- * The value is {@value}
- */
- String TYPE = "job";
-
- /**
- * Returns the identifier of the job.
- *
- * @return the job identifier.
- */
- String getId();
-
- /**
- * Returns the name of the job.
- *
- * @return the job name.
- */
- String getName();
-
- /**
- * Retrieves the current state of the job.
- *
- * @return the current state.
- */
- Job.State getCurrentState();
-
- /**
- * Retrieves the next execution state when the job makes a state
- * transition.
- *
- * @return the destination state while in a state transition.
- */
- Job.State getNextState();
-
- /**
- * Returns the summarized health indicator of the job.
- *
- * @return the summarized Job health.
- */
- Job.Health getHealth();
-
- /**
- * Returns the last error message caught by the current job execution.
- * @return the last error message or an empty string if no error has
- * been caught.
- */
- String getLastError();
-
- /**
- * Takes a current snapshot of the running graph and returns it in JSON format.
- * <p>
- * <b>The graph snapshot JSON format</b>
- * <p>
- * The top-level object contains two properties:
- * <ul>
- * <li>{@code vertices}: Array of JSON objects representing the graph vertices.</li>
- * <li>{@code edges}: Array of JSON objects representing the graph edges (an edge joins two vertices).</li>
- * </ul>
- * The vertex object contains the following properties:
- * <ul>
- * <li>{@code id}: Unique identifier within a graph's JSON representation.</li>
- * <li>{@code instance}: The oplet instance from the vertex.</li>
- * </ul>
- * The edge object contains the following properties:
- * <ul>
- * <li>{@code sourceId}: The identifier of the source vertex.</li>
- * <li>{@code sourceOutputPort}: The identifier of the source oplet output port connected to the edge.</li>
- * <li>{@code targetId}: The identifier of the target vertex.</li>
- * <li>{@code targetInputPort}: The identifier of the target oplet input port connected to the edge.</li>
- * </ul>
- *
- * @return a JSON-formatted string representing the running graph.
- */
- String graphSnapshot();
-
- /**
- * Initiates an execution state change.
- *
- * @param action which triggers the state change.
- * @throws IllegalArgumentException if the job is not in an appropriate
- * state for the requested action, or the action is not supported.
- */
- void stateChange(Action action);
-}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/mbeans/PeriodMXBean.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/mbeans/PeriodMXBean.java b/api/execution/src/main/java/edgent/execution/mbeans/PeriodMXBean.java
deleted file mode 100644
index 53d768b..0000000
--- a/api/execution/src/main/java/edgent/execution/mbeans/PeriodMXBean.java
+++ /dev/null
@@ -1,62 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-package edgent.execution.mbeans;
-
-import java.util.concurrent.TimeUnit;
-
-/**
- * Control mbean interface for an entity having an a time period control.
- * <P>
- * This mbean lacks a {@code TYPE} declaration because it's
- * a generic control interface applicable to a variety of
- * object types (e.g., a stream or window).
- * The type of the associated object is to be used when
- * registering instances of this mbean with the
- * {@link edgent.execution.services.ControlService ControlService}.
- * </P>
- *
- * @see edgent.topology.Topology#poll(edgent.function.Supplier, long, TimeUnit)
- */
-public interface PeriodMXBean {
-
- /**
- * Get the period.
- * @return period
- */
- public long getPeriod();
-
- /**
- * Get the time unit for {@link #getPeriod()}.
- * @return time unit
- */
- public TimeUnit getUnit();
-
- /**
- * Set the period.
- * @param period the period
- */
- public void setPeriod(long period);
-
- /**
- * Set the period and unit
- * @param period the period
- * @param unit the {@link TimeUnit} of {@code period}
- */
- public void setPeriod(long period, TimeUnit unit);
-}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/mbeans/package-info.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/mbeans/package-info.java b/api/execution/src/main/java/edgent/execution/mbeans/package-info.java
deleted file mode 100644
index 6fc6895..0000000
--- a/api/execution/src/main/java/edgent/execution/mbeans/package-info.java
+++ /dev/null
@@ -1,23 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-/**
- * Management MBeans for execution.
- *
- */
-package edgent.execution.mbeans;
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/package-info.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/package-info.java b/api/execution/src/main/java/edgent/execution/package-info.java
deleted file mode 100644
index 7f6a042..0000000
--- a/api/execution/src/main/java/edgent/execution/package-info.java
+++ /dev/null
@@ -1,23 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-/**
- * Execution of Edgent topologies and graphs.
- *
- */
-package edgent.execution;
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/services/ControlService.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/services/ControlService.java b/api/execution/src/main/java/edgent/execution/services/ControlService.java
deleted file mode 100644
index abfb5e3..0000000
--- a/api/execution/src/main/java/edgent/execution/services/ControlService.java
+++ /dev/null
@@ -1,123 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-package edgent.execution.services;
-
-/**
- * Service that provides a control mechanism.
- * <BR>
- * The control service allows applications and Edgent itself to
- * register control interfaces generically. The style of a control interface
- * is similar to a JMX Management Bean (MBean), specifically a JMX MXBean.
- * <BR>
- * No dependency is created on any JMX interface to allow running on systems
- * that do not support JMX, such as Android.
- * <P>
- * Different implementations of the control service provide the mechanism
- * to execute methods of the control interfaces. For example
- * {@link edgent.runtime.jmxcontrol.JMXControlService JMXControlService}
- * registers the MBeans in the JMX platform MBean server.
- * <BR>
- * The control service is intended to allow remote execution of a control interface
- * through any mechanism. The control service provides operations and attributes
- * similar to JMX. It does not provide notifications.
- * </P>
- * <P>
- * An instance of a control service MBean is defined by its:
- * </P>
- * <UL>
- * <LI> A type </LI>
- * <LI> A identifier - Unique within the current execution context.</LI>
- * <LI> An alias - Optional, but can be combined with the control MBeans's type
- * to logically identify a control MBean. </LI>
- * <LI> A Java interface - This defines what operations can be executed
- * against the control MBean.</LI>
- * </UL>
- * <P>
- * A remote system should be able to specify an operation on an
- * control server MBean though its alias and type. For example
- * an application might be submitted with a fixed name
- * <em>PumpAnalytics</em> (as its alias)
- * to allow its {@link edgent.execution.mbeans.JobMXBean JobMXBean}
- * to be determined remotely using a combination of
- * {@link edgent.execution.mbeans.JobMXBean#TYPE JobMXBean.TYPE}
- * and <em>PumpAnalytics</em>.
- * </P>
- * <P>
- * Control service implementations may be limited in their capabilities,
- * for example when using the JMX control service the full capabilities
- * of JMX can be used, such as complex types in a control service MBean interface.
- * Portable applications would limit themselves to a smaller subset of
- * capabilities, such as only primitive types and enums.
- * <BR>
- * The method {@link Controls#isControlServiceMBean(Class)} defines
- * the minimal supported interface for any control service.
- * </P>
- */
-public interface ControlService {
-
- /**
- * Register a control MBean.
- *
- * @param <T> Control MBean type
- * @param type Type of the control MBean.
- * @param id
- * Unique identifier for the control MBean.
- * @param alias
- * Alias for the control MBean. Required to be unique within the context
- * of {@code type}.
- * @param controlInterface
- * Public interface for the control MBean.
- * @param control
- * The control MBean
- * @return unique identifier that can be used to unregister an control MBean.
- */
- <T> String registerControl(String type, String id, String alias, Class<T> controlInterface, T control);
-
- /**
- * Unregister a control bean registered by {@link #registerControl(String, String, String, Class, Object)}
- * @param controlId control's registration identifier returned by {@code registerControl}
- */
- void unregister(String controlId);
-
- /**
- * Return a control Mbean registered with this service.
- *
- * @param <T> Control MBean type
- * @param type Type of the control MBean.
- * @param alias Alias for the control MBean.
- * @param controlInterface
- * Public interface of the control MBean.
- * @return Control Mbean or null if a matching MBean is not registered.
- */
- <T> T getControl(String type, String alias, Class<T> controlInterface);
-
- /**
- * Return the unique identifier for a control Mbean registered with
- * this service.
- *
- * @param <T> Control MBean type
- * @param type Type of the control MBean.
- * @param alias Alias for the control MBean.
- * @param controlInterface
- * Public interface of the control MBean.
- * @return unique identifier that can be used to unregister a control
- * MBean or null if a matching MBean is not registered.
- */
- <T> String getControlId(String type, String alias, Class<T> controlInterface);
-}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/services/Controls.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/services/Controls.java b/api/execution/src/main/java/edgent/execution/services/Controls.java
deleted file mode 100644
index befe0b4..0000000
--- a/api/execution/src/main/java/edgent/execution/services/Controls.java
+++ /dev/null
@@ -1,99 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-package edgent.execution.services;
-
-import java.lang.reflect.Method;
-
-/**
- * Utilities for the control service.
- *
- * @see ControlService
- */
-public class Controls {
- /**
- * Number of seconds a {@link edgent.execution.mbeans.JobMXBean JobMXBean}
- * control is held registered with the {@link ControlService} after a job
- * gets closed. After this period the bean gets unregistered from the
- * service.
- */
- public final static int JOB_HOLD_AFTER_CLOSE_SECS = 10;
-
- /**
- * Test to see if an interface represents a valid
- * control service MBean.
- * All implementations of {@code ControlService}
- * must support control MBeans for which this
- * method returns true.
- * <BR>
- * An interface is a valid control service MBean if
- * all of the following are true:
- * <UL>
- * <LI>An interface that does not extend any other interface.</LI>
- * <LI>Not be parameterized</LI>
- * <LI>Method parameters and return types restricted to these types:
- * <UL>
- * <LI>{@code String, boolean, int, long, double}.</LI>
- * <LI>Any enumeration</LI>
- * </UL>
- * </UL>
- * @param controlInterface class of the control interface
- * @return True
- */
- public static boolean isControlServiceMBean(Class<?> controlInterface) {
-
- if (!controlInterface.isInterface())
- return false;
-
- if (controlInterface.getInterfaces().length != 0)
- return false;
-
- if (controlInterface.getTypeParameters().length != 0)
- return false;
-
- for (Method cim : controlInterface.getDeclaredMethods()) {
- if (cim.getReturnType() != Void.TYPE
- && !validType(cim.getReturnType()))
- return false;
-
- for (Class<?> ptt : cim.getParameterTypes()) {
- if (!validType(ptt))
- return false;
- }
- }
-
- return true;
- }
-
- static boolean validType(Class<?> type) {
- if (String.class == type)
- return true;
- if (Boolean.TYPE == type)
- return true;
- if (Integer.TYPE == type)
- return true;
- if (Long.TYPE == type)
- return true;
- if (Double.TYPE == type)
- return true;
- if (type.isEnum())
- return true;
-
- return false;
- }
-}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/services/JobRegistryService.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/services/JobRegistryService.java b/api/execution/src/main/java/edgent/execution/services/JobRegistryService.java
deleted file mode 100644
index 88fee24..0000000
--- a/api/execution/src/main/java/edgent/execution/services/JobRegistryService.java
+++ /dev/null
@@ -1,126 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-package edgent.execution.services;
-
-import java.util.Set;
-
-import edgent.execution.Job;
-import edgent.function.BiConsumer;
-
-/**
- * Job registry service.
- * <p>
- * Keeps the list of {@link Job} instances registered by the runtime and
- * provides the necessary methods to register and remove jobs, access
- * registered jobs, as well as register listeners which are notified on job
- * registrations, removals, and updates.
- * The following event types are sent to registered listeners:
- * </p>
- * <ul>
- * <li>An {@link EventType#ADD} event is sent when a job is added.</li>
- * <li>An {@link EventType#REMOVE} event is sent when a job is removed.</li>
- * <li>An {@link EventType#UPDATE} event is sent when a job is updated.</li>
- * </ul>
- * <h3>Event dispatch</h3>
- * If a listener invocation throws an Exception, then the exception
- * will not prevent the remaining listeners from being invoked. However,
- * if the invocation throws an Error, then it is recommended that
- * the event dispatch stop.
- */
-public interface JobRegistryService {
- /**
- * Job event types.
- */
- enum EventType {
- /** A Job has been added to the registry. */
- ADD,
- /** A Job has been removed from the registry. */
- REMOVE,
- /** A registered Job has been updated. */
- UPDATE
- }
-
- /**
- * Adds a handler to a collection of listeners that will be notified
- * on job registration and state changes. Listeners will be notified
- * in the order in which they are added.
- * <p>
- * A listener is notified of all existing jobs when it is first added.
- *
- * @param listener the listener that will be added
- * @throws IllegalArgumentException if the listener parameter is
- * {@code null}
- */
- void addListener(BiConsumer<JobRegistryService.EventType, Job> listener)
- throws IllegalArgumentException;
-
- /**
- * Removes a handler from this registry's collection of listeners.
- *
- * @param listener the listener that will be removed
- * @return whether or not the listener has been removed
- */
- boolean removeListener(
- BiConsumer<JobRegistryService.EventType, Job> listener);
-
- /**
- * Returns a set of all the registered job identifiers.
- *
- * @return the identifiers of all the jobs
- */
- Set<String> getJobIds();
-
- /**
- * Returns a job given its identifier.
- *
- * @param id job identifier
- * @return the job or {@code null} if no job is registered with that
- * identifier.
- */
- Job getJob(String id);
-
- /**
- * Adds the specified job.
- *
- * @param job the job to register
- *
- * @throws IllegalArgumentException if a job is null, or if a job with
- * the same identifier is already registered
- */
- void addJob(Job job) throws IllegalArgumentException;
-
- /**
- * Removes the job specified by the given identifier.
- *
- * @param jobId the identifier of the job to remove
- * @return whether or not the job was removed
- */
- boolean removeJob(String jobId);
-
- /**
- * Notifies listeners that the specified registered job has
- * been updated.
- *
- * @param job the job
- * @return whether or not the job was found in the registry
- */
- boolean updateJob(Job job);
-
- // TODO add job retrieval given its name
-}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/services/RuntimeServices.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/services/RuntimeServices.java b/api/execution/src/main/java/edgent/execution/services/RuntimeServices.java
deleted file mode 100644
index c646002..0000000
--- a/api/execution/src/main/java/edgent/execution/services/RuntimeServices.java
+++ /dev/null
@@ -1,74 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-package edgent.execution.services;
-
-/**
- * At runtime a container provides services to
- * executing elements such as oplets and functions.
- *
- * <P>
- * Services, providers and applications can optionally store
- * preferences (configuration information) using a {@code java.util.pref.Preferences}
- * instance registered as a service. Any provider may optionally register
- * a root {@code Preferences} node. Once a provider registers
- * a {@code Preferences} node, preferences will
- * be saved across reboots of the provider and/or JVM if the underlying
- * {@code Preferences} implementation supports it.
- *
- * <BR>
- * Services and application code can store keys
- * in the root {@code Preferences} node or create child nodes
- * as required.
- * <pre>
- * <code>
- * Preferences prefs = rs.getService(Preferences.class);
- * if (prefs != null) {
- * prefs.put("threshold", 3);
- * }
- * </code>
- * </pre>
- * </P>
- *
- */
-public interface RuntimeServices {
-
- /**
- * Get a service for this invocation.
- * <P>
- * These services must be provided by all implementations:
- * </P>
- * <UL>
- * <LI>
- * {@code java.util.concurrent.ThreadFactory} - Thread factory, runtime code should
- * create new threads using this factory.
- * </LI>
- * <LI>
- * {@code java.util.concurrent.ScheduledExecutorService} - Scheduler, runtime code should
- * execute asynchronous and repeating tasks using this scheduler.
- * </LI>
- * </UL>
- *
- * @param <T> service class type
- * @param serviceClass Type of the service required.
- * @return Service of type implementing {@code serviceClass} if the
- * container this invocation runs in supports that service,
- * otherwise {@code null}.
- */
- <T> T getService(Class<T> serviceClass);
-}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/services/ServiceContainer.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/services/ServiceContainer.java b/api/execution/src/main/java/edgent/execution/services/ServiceContainer.java
deleted file mode 100644
index c4bff76..0000000
--- a/api/execution/src/main/java/edgent/execution/services/ServiceContainer.java
+++ /dev/null
@@ -1,125 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-package edgent.execution.services;
-
-import java.util.Collections;
-import java.util.HashMap;
-import java.util.HashSet;
-import java.util.Map;
-import java.util.Set;
-
-import edgent.execution.Job;
-import edgent.function.BiConsumer;
-
-/**
- * Provides a container for services.
- * <p>
- * The current implementation does not downcast the provided service class
- * when searching for an appropriate service implementation. For example:
- * <pre>
- * class Derived extends Base {}
- *
- * serviceContainer.add(Derived.class, instanceOfDerived);
- *
- * // Searching for the base class returns null
- * assert(null == serviceContainer.get(Base.class, instanceOfDerived));
- * </pre>
- */
-public class ServiceContainer {
- private final Map<Class<?>, Object> services;
- private final Set<BiConsumer<String,String>> cleaners;
-
- public ServiceContainer() {
- this.services = Collections.synchronizedMap(new HashMap<>());
- cleaners = Collections.synchronizedSet(new HashSet<>());
- }
-
- /**
- * Adds the specified service to this {@code ServiceContainer}.
- * <p>
- * Associates the specified service with the service class. If the
- * container has previously contained a service for the class,
- * the old value is replaced by the specified value.
- *
- * @param <T> service class type
- * @param serviceClass the class of service to add.
- * @param service service to add to this container.
- * @return the previous value associated with {@code serviceClass}, or
- * {@code null} if there was no registered mapping.
- * @throws NullPointerException if the specified service class or
- * service is null.
- */
- public <T> T addService(Class<T> serviceClass, T service) {
- return serviceClass.cast(services.put(serviceClass, service));
- }
-
- /**
- * Removes the specified service from this {@code ServiceContainer}.
- *
- * @param <T> service class type
- * @param serviceClass the class of service to remove.
- * @return the service previously associated with the service class, or
- * {@code null} if there was no registered service.
- * @throws NullPointerException if the specified service class is null.
- */
- public <T> T removeService(Class<T> serviceClass) {
- return serviceClass.cast(services.remove(serviceClass));
- }
-
- /**
- * Returns the service to which the specified service class key is
- * mapped, or {@code null} if this {@code ServiceContainer} contains no
- * service for that key.
- *
- * @param <T> service class type
- * @param serviceClass the class whose associated service is to be returned
- * @return the service instance mapped to the specified service class, or
- * {@code null} if no service is registered for the class.
- */
- public <T> T getService(Class<T> serviceClass) {
- return serviceClass.cast(services.get(serviceClass));
- }
-
- /**
- * Registers a new cleaner.
- * <p>
- * A cleaner is a hook which is invoked when the runtime
- * closes an element of {@link Job}.
- * When an element of job is closed {@code cleaner.accept(jobId, elementId)}
- * is called where {@code jobId} is the {@link Job#getId() job identifier} and
- * {@code elementId} is the unique identifier for the element.
- *
- * @param cleaner The cleaner.
- */
- public void addCleaner(BiConsumer<String,String> cleaner) {
- cleaners.add(cleaner);
- }
-
- /**
- * Invokes all the registered cleaners in the context of the specified
- * job and element.
- *
- * @param jobId The job identifier.
- * @param elementId The element identifier.
- */
- public void cleanOplet(String jobId, String elementId) {
- for (BiConsumer<String,String> cleaner : cleaners)
- cleaner.accept(jobId, elementId);
- }
-}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/edgent/execution/services/package-info.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/edgent/execution/services/package-info.java b/api/execution/src/main/java/edgent/execution/services/package-info.java
deleted file mode 100644
index 8d1f662..0000000
--- a/api/execution/src/main/java/edgent/execution/services/package-info.java
+++ /dev/null
@@ -1,22 +0,0 @@
-/*
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
-*/
-/**
- * Execution services.
- */
-package edgent.execution.services;
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/Configs.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/Configs.java b/api/execution/src/main/java/org/apache/edgent/execution/Configs.java
new file mode 100644
index 0000000..f4b8425
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/Configs.java
@@ -0,0 +1,51 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+package org.apache.edgent.execution;
+
+/**
+ * Configuration property names.
+ *
+ * Configuration is passed as a JSON collection of name/value
+ * pairs when an executable is
+ * {@linkplain org.apache.edgent.execution.Submitter#submit(Object, com.google.gson.JsonObject) submitted}.
+ * <p>
+ * The configuration JSON representation is summarized in the following table:
+ * </p>
+ * <table border=1 cellpadding=3 cellspacing=1>
+ * <caption>Summary of configuration properties</caption>
+ * <tr>
+ * <th align=center><b>Attribute name</b></th>
+ * <th align=center><b>Type</b></th>
+ * <th align=center><b>Description</b></th>
+ * </tr>
+ * <tr>
+ * <td>{@link #JOB_NAME jobName}</td>
+ * <td>String</td>
+ * <td>The name of the job.</td>
+ * </tr>
+ * </table>
+ */
+public interface Configs {
+ /**
+ * JOB_NAME is used to identify the submission configuration property
+ * containing the job name.
+ * The value is {@value}.
+ */
+ String JOB_NAME = "jobName";
+}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/DirectSubmitter.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/DirectSubmitter.java b/api/execution/src/main/java/org/apache/edgent/execution/DirectSubmitter.java
new file mode 100644
index 0000000..437aeed
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/DirectSubmitter.java
@@ -0,0 +1,44 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+package org.apache.edgent.execution;
+
+import org.apache.edgent.execution.services.ServiceContainer;
+
+/**
+ * An interface for submission of an executable
+ * that is executed directly within the current
+ * virtual machine.
+ *
+ * @param <E> the executable type
+ * @param <J> the submitted executable's future
+ */
+public interface DirectSubmitter<E, J extends Job> extends Submitter<E,J> {
+
+ /**
+ * Access to services.
+ *
+ * Since any executables are executed directly within
+ * the current virtual machine, callers may register
+ * services that are visible to the executable
+ * and its elements.
+ *
+ * @return Service container for this submitter.
+ */
+ ServiceContainer getServices();
+}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/Job.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/Job.java b/api/execution/src/main/java/org/apache/edgent/execution/Job.java
new file mode 100644
index 0000000..fc178ff
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/Job.java
@@ -0,0 +1,182 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+package org.apache.edgent.execution;
+
+import java.util.concurrent.ExecutionException;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
+
+/**
+ * Actions and states for execution of an Edgent job.
+ *
+ * The interface provides the main job lifecycle control, taking on the following
+ * execution state values:
+ *
+ * <ul>
+ * <li><b>CONSTRUCTED</b> This job has been constructed but the
+ * nodes are not yet initialized.</li>
+ * <li><b>INITIALIZED</b> This job has been initialized and is
+ * ready to process data.
+ * <li><b>RUNNING</b> This job is processing data.</li>
+ * <li><b>PAUSED</b> This job is paused.</li>
+ * <li><b>CLOSED</b> This job is closed.</li>
+ * </ul>
+ *
+ * The interface provides access to two state values:
+ * <ul>
+ * <li> {@link #getCurrentState() Current} - The current state of execution
+ * when the job is not executing a state transition; the source state
+ * while the job is making a state transition after the client code
+ * calls {@link #stateChange(Job.Action)}.</li>
+ * <li> {@link #getNextState() Next} - The destination state while the job
+ * is making a state transition; same as the current state while
+ * the job state is stable (that is, not making a transition).</LI>
+ * </ul>
+ *
+ * The interface provides access to the job nodes
+ * {@linkplain #getHealth() health summary}, described by the following values:
+ * <ul>
+ * <li><b>HEALTHY</b> All graph nodes in the job are healthy.</li>
+ * <li><b>UNHEALTHY</b> At least one graph node in the job is stopped or
+ * stopping.</li>
+ * </ul>
+ */
+public interface Job {
+ /**
+ * States of a graph job.
+ */
+ public enum State {
+ /** Initial state, the graph nodes are not yet initialized. */
+ CONSTRUCTED,
+ /** All the graph nodes have been initialized. */
+ INITIALIZED,
+ /** All the graph nodes are processing data. */
+ RUNNING,
+ /** All the graph nodes are paused. */
+ PAUSED,
+ /** All the graph nodes are closed. */
+ CLOSED
+ }
+
+ /**
+ * Enumeration for the summarized health indicator of the graph nodes.
+ */
+ public enum Health {
+ /**
+ * All graph nodes in the job are healthy.
+ */
+ HEALTHY,
+ /**
+ * The execution of at least one graph node in the job has stopped
+ * because of an abnormal condition.
+ */
+ UNHEALTHY
+ }
+
+ /**
+ * Actions which trigger {@link Job.State} transitions.
+ */
+ public enum Action {
+ /** Initialize the job */
+ INITIALIZE,
+ /** Start the execution. */
+ START,
+ /** Pause the execution. */
+ PAUSE,
+ /** Resume the execution */
+ RESUME,
+ /** Close the job. */
+ CLOSE
+ }
+
+ /**
+ * Retrieves the current state of this job.
+ *
+ * @return the current state.
+ */
+ State getCurrentState();
+
+ /**
+ * Retrieves the next execution state when this job makes a state
+ * transition.
+ *
+ * @return the destination state while in a state transition;
+ * otherwise the same as {@link #getCurrentState()}.
+ */
+ State getNextState();
+
+ /**
+ * Initiates an execution state change.
+ *
+ * @param action which triggers the state change.
+ * @throws IllegalArgumentException if the job is not in an appropriate
+ * state for the requested action, or the action is not supported.
+ */
+ void stateChange(Action action) throws IllegalArgumentException;
+
+ /**
+ * Returns the summarized health indicator of the graph nodes.
+ *
+ * @return the summarized Job node health.
+ */
+ Health getHealth();
+
+ /**
+ * Returns the last error message caught by the current job execution.
+ * @return the last error message or an empty string if no error has
+ * been caught.
+ */
+ String getLastError();
+
+ /**
+ * Returns the name of this job. The name may be set when the job is
+ * {@linkplain org.apache.edgent.execution.Submitter#submit(java.lang.Object,com.google.gson.JsonObject) submitted}.
+ * Implementations may create a job name if one is not specified at submit time.
+ *
+ * @return the job name.
+ */
+ String getName();
+
+ /**
+ * Returns the identifier of this job.
+ *
+ * @return this job identifier.
+ */
+ String getId();
+
+ /**
+ * Waits for any outstanding job work to complete.
+ *
+ * @throws ExecutionException if the job execution threw an exception.
+ * @throws InterruptedException if the current thread was interrupted while waiting
+ */
+ void complete() throws ExecutionException, InterruptedException;
+
+ /**
+ * Waits for at most the specified time for the job to complete.
+ *
+ * @param timeout the time to wait
+ * @param unit the time unit of the timeout argument
+ *
+ * @throws ExecutionException if the job execution threw an exception.
+ * @throws InterruptedException if the current thread was interrupted while waiting
+ * @throws TimeoutException if the wait timed out
+ */
+ void complete(long timeout, TimeUnit unit) throws ExecutionException, InterruptedException, TimeoutException;
+}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/Submitter.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/Submitter.java b/api/execution/src/main/java/org/apache/edgent/execution/Submitter.java
new file mode 100644
index 0000000..531eb4d
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/Submitter.java
@@ -0,0 +1,56 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+package org.apache.edgent.execution;
+
+import java.util.concurrent.Future;
+
+import com.google.gson.JsonObject;
+
+
+/**
+ * An interface for submission of an executable.
+ * <p>
+ * The class implementing this interface is responsible
+ * for the semantics of this operation. e.g., an direct topology
+ * provider would run the topology as threads in the current jvm.
+ *
+ * @param <E> the executable type
+ * @param <J> the submitted executable's future
+ */
+public interface Submitter<E, J extends Job> {
+
+ /**
+ * Submit an executable.
+ * No configuration options are specified,
+ * this is equivalent to {@code submit(executable, new JsonObject())}.
+ *
+ * @param executable executable to submit
+ * @return a future for the submitted executable
+ */
+ Future<J> submit(E executable);
+
+ /**
+ * Submit an executable.
+ *
+ * @param executable executable to submit
+ * @param config context {@linkplain org.apache.edgent.execution.Configs information} for the submission
+ * @return a future for the submitted executable
+ */
+ Future<J> submit(E executable, JsonObject config);
+}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/mbeans/JobMXBean.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/mbeans/JobMXBean.java b/api/execution/src/main/java/org/apache/edgent/execution/mbeans/JobMXBean.java
new file mode 100644
index 0000000..d28d09b
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/mbeans/JobMXBean.java
@@ -0,0 +1,114 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+package org.apache.edgent.execution.mbeans;
+
+
+import org.apache.edgent.execution.Job;
+import org.apache.edgent.execution.Job.Action;
+
+
+/**
+ * Control interface for a job.
+ */
+public interface JobMXBean {
+ /**
+ * TYPE is used to identify this bean as a job bean when building the bean's {@code ObjectName}.
+ * The value is {@value}
+ */
+ String TYPE = "job";
+
+ /**
+ * Returns the identifier of the job.
+ *
+ * @return the job identifier.
+ */
+ String getId();
+
+ /**
+ * Returns the name of the job.
+ *
+ * @return the job name.
+ */
+ String getName();
+
+ /**
+ * Retrieves the current state of the job.
+ *
+ * @return the current state.
+ */
+ Job.State getCurrentState();
+
+ /**
+ * Retrieves the next execution state when the job makes a state
+ * transition.
+ *
+ * @return the destination state while in a state transition.
+ */
+ Job.State getNextState();
+
+ /**
+ * Returns the summarized health indicator of the job.
+ *
+ * @return the summarized Job health.
+ */
+ Job.Health getHealth();
+
+ /**
+ * Returns the last error message caught by the current job execution.
+ * @return the last error message or an empty string if no error has
+ * been caught.
+ */
+ String getLastError();
+
+ /**
+ * Takes a current snapshot of the running graph and returns it in JSON format.
+ * <p>
+ * <b>The graph snapshot JSON format</b>
+ * <p>
+ * The top-level object contains two properties:
+ * <ul>
+ * <li>{@code vertices}: Array of JSON objects representing the graph vertices.</li>
+ * <li>{@code edges}: Array of JSON objects representing the graph edges (an edge joins two vertices).</li>
+ * </ul>
+ * The vertex object contains the following properties:
+ * <ul>
+ * <li>{@code id}: Unique identifier within a graph's JSON representation.</li>
+ * <li>{@code instance}: The oplet instance from the vertex.</li>
+ * </ul>
+ * The edge object contains the following properties:
+ * <ul>
+ * <li>{@code sourceId}: The identifier of the source vertex.</li>
+ * <li>{@code sourceOutputPort}: The identifier of the source oplet output port connected to the edge.</li>
+ * <li>{@code targetId}: The identifier of the target vertex.</li>
+ * <li>{@code targetInputPort}: The identifier of the target oplet input port connected to the edge.</li>
+ * </ul>
+ *
+ * @return a JSON-formatted string representing the running graph.
+ */
+ String graphSnapshot();
+
+ /**
+ * Initiates an execution state change.
+ *
+ * @param action which triggers the state change.
+ * @throws IllegalArgumentException if the job is not in an appropriate
+ * state for the requested action, or the action is not supported.
+ */
+ void stateChange(Action action);
+}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/mbeans/PeriodMXBean.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/mbeans/PeriodMXBean.java b/api/execution/src/main/java/org/apache/edgent/execution/mbeans/PeriodMXBean.java
new file mode 100644
index 0000000..54d3b5b
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/mbeans/PeriodMXBean.java
@@ -0,0 +1,62 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+package org.apache.edgent.execution.mbeans;
+
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Control mbean interface for an entity having an a time period control.
+ * <P>
+ * This mbean lacks a {@code TYPE} declaration because it's
+ * a generic control interface applicable to a variety of
+ * object types (e.g., a stream or window).
+ * The type of the associated object is to be used when
+ * registering instances of this mbean with the
+ * {@link org.apache.edgent.execution.services.ControlService ControlService}.
+ * </P>
+ *
+ * @see org.apache.edgent.topology.Topology#poll(org.apache.edgent.function.Supplier, long, TimeUnit)
+ */
+public interface PeriodMXBean {
+
+ /**
+ * Get the period.
+ * @return period
+ */
+ public long getPeriod();
+
+ /**
+ * Get the time unit for {@link #getPeriod()}.
+ * @return time unit
+ */
+ public TimeUnit getUnit();
+
+ /**
+ * Set the period.
+ * @param period the period
+ */
+ public void setPeriod(long period);
+
+ /**
+ * Set the period and unit
+ * @param period the period
+ * @param unit the {@link TimeUnit} of {@code period}
+ */
+ public void setPeriod(long period, TimeUnit unit);
+}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/mbeans/package-info.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/mbeans/package-info.java b/api/execution/src/main/java/org/apache/edgent/execution/mbeans/package-info.java
new file mode 100644
index 0000000..021bd90
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/mbeans/package-info.java
@@ -0,0 +1,23 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+/**
+ * Management MBeans for execution.
+ *
+ */
+package org.apache.edgent.execution.mbeans;
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/package-info.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/package-info.java b/api/execution/src/main/java/org/apache/edgent/execution/package-info.java
new file mode 100644
index 0000000..8b16186
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/package-info.java
@@ -0,0 +1,23 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+/**
+ * Execution of Edgent topologies and graphs.
+ *
+ */
+package org.apache.edgent.execution;
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/services/ControlService.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/services/ControlService.java b/api/execution/src/main/java/org/apache/edgent/execution/services/ControlService.java
new file mode 100644
index 0000000..635ae92
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/services/ControlService.java
@@ -0,0 +1,123 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+package org.apache.edgent.execution.services;
+
+/**
+ * Service that provides a control mechanism.
+ * <BR>
+ * The control service allows applications and Edgent itself to
+ * register control interfaces generically. The style of a control interface
+ * is similar to a JMX Management Bean (MBean), specifically a JMX MXBean.
+ * <BR>
+ * No dependency is created on any JMX interface to allow running on systems
+ * that do not support JMX, such as Android.
+ * <P>
+ * Different implementations of the control service provide the mechanism
+ * to execute methods of the control interfaces. For example
+ * {@link org.apache.edgent.runtime.jmxcontrol.JMXControlService JMXControlService}
+ * registers the MBeans in the JMX platform MBean server.
+ * <BR>
+ * The control service is intended to allow remote execution of a control interface
+ * through any mechanism. The control service provides operations and attributes
+ * similar to JMX. It does not provide notifications.
+ * </P>
+ * <P>
+ * An instance of a control service MBean is defined by its:
+ * </P>
+ * <UL>
+ * <LI> A type </LI>
+ * <LI> A identifier - Unique within the current execution context.</LI>
+ * <LI> An alias - Optional, but can be combined with the control MBeans's type
+ * to logically identify a control MBean. </LI>
+ * <LI> A Java interface - This defines what operations can be executed
+ * against the control MBean.</LI>
+ * </UL>
+ * <P>
+ * A remote system should be able to specify an operation on an
+ * control server MBean though its alias and type. For example
+ * an application might be submitted with a fixed name
+ * <em>PumpAnalytics</em> (as its alias)
+ * to allow its {@link org.apache.edgent.execution.mbeans.JobMXBean JobMXBean}
+ * to be determined remotely using a combination of
+ * {@link org.apache.edgent.execution.mbeans.JobMXBean#TYPE JobMXBean.TYPE}
+ * and <em>PumpAnalytics</em>.
+ * </P>
+ * <P>
+ * Control service implementations may be limited in their capabilities,
+ * for example when using the JMX control service the full capabilities
+ * of JMX can be used, such as complex types in a control service MBean interface.
+ * Portable applications would limit themselves to a smaller subset of
+ * capabilities, such as only primitive types and enums.
+ * <BR>
+ * The method {@link Controls#isControlServiceMBean(Class)} defines
+ * the minimal supported interface for any control service.
+ * </P>
+ */
+public interface ControlService {
+
+ /**
+ * Register a control MBean.
+ *
+ * @param <T> Control MBean type
+ * @param type Type of the control MBean.
+ * @param id
+ * Unique identifier for the control MBean.
+ * @param alias
+ * Alias for the control MBean. Required to be unique within the context
+ * of {@code type}.
+ * @param controlInterface
+ * Public interface for the control MBean.
+ * @param control
+ * The control MBean
+ * @return unique identifier that can be used to unregister an control MBean.
+ */
+ <T> String registerControl(String type, String id, String alias, Class<T> controlInterface, T control);
+
+ /**
+ * Unregister a control bean registered by {@link #registerControl(String, String, String, Class, Object)}
+ * @param controlId control's registration identifier returned by {@code registerControl}
+ */
+ void unregister(String controlId);
+
+ /**
+ * Return a control Mbean registered with this service.
+ *
+ * @param <T> Control MBean type
+ * @param type Type of the control MBean.
+ * @param alias Alias for the control MBean.
+ * @param controlInterface
+ * Public interface of the control MBean.
+ * @return Control Mbean or null if a matching MBean is not registered.
+ */
+ <T> T getControl(String type, String alias, Class<T> controlInterface);
+
+ /**
+ * Return the unique identifier for a control Mbean registered with
+ * this service.
+ *
+ * @param <T> Control MBean type
+ * @param type Type of the control MBean.
+ * @param alias Alias for the control MBean.
+ * @param controlInterface
+ * Public interface of the control MBean.
+ * @return unique identifier that can be used to unregister a control
+ * MBean or null if a matching MBean is not registered.
+ */
+ <T> String getControlId(String type, String alias, Class<T> controlInterface);
+}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/services/Controls.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/services/Controls.java b/api/execution/src/main/java/org/apache/edgent/execution/services/Controls.java
new file mode 100644
index 0000000..3ee31cb
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/services/Controls.java
@@ -0,0 +1,99 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+package org.apache.edgent.execution.services;
+
+import java.lang.reflect.Method;
+
+/**
+ * Utilities for the control service.
+ *
+ * @see ControlService
+ */
+public class Controls {
+ /**
+ * Number of seconds a {@link org.apache.edgent.execution.mbeans.JobMXBean JobMXBean}
+ * control is held registered with the {@link ControlService} after a job
+ * gets closed. After this period the bean gets unregistered from the
+ * service.
+ */
+ public final static int JOB_HOLD_AFTER_CLOSE_SECS = 10;
+
+ /**
+ * Test to see if an interface represents a valid
+ * control service MBean.
+ * All implementations of {@code ControlService}
+ * must support control MBeans for which this
+ * method returns true.
+ * <BR>
+ * An interface is a valid control service MBean if
+ * all of the following are true:
+ * <UL>
+ * <LI>An interface that does not extend any other interface.</LI>
+ * <LI>Not be parameterized</LI>
+ * <LI>Method parameters and return types restricted to these types:
+ * <UL>
+ * <LI>{@code String, boolean, int, long, double}.</LI>
+ * <LI>Any enumeration</LI>
+ * </UL>
+ * </UL>
+ * @param controlInterface class of the control interface
+ * @return True
+ */
+ public static boolean isControlServiceMBean(Class<?> controlInterface) {
+
+ if (!controlInterface.isInterface())
+ return false;
+
+ if (controlInterface.getInterfaces().length != 0)
+ return false;
+
+ if (controlInterface.getTypeParameters().length != 0)
+ return false;
+
+ for (Method cim : controlInterface.getDeclaredMethods()) {
+ if (cim.getReturnType() != Void.TYPE
+ && !validType(cim.getReturnType()))
+ return false;
+
+ for (Class<?> ptt : cim.getParameterTypes()) {
+ if (!validType(ptt))
+ return false;
+ }
+ }
+
+ return true;
+ }
+
+ static boolean validType(Class<?> type) {
+ if (String.class == type)
+ return true;
+ if (Boolean.TYPE == type)
+ return true;
+ if (Integer.TYPE == type)
+ return true;
+ if (Long.TYPE == type)
+ return true;
+ if (Double.TYPE == type)
+ return true;
+ if (type.isEnum())
+ return true;
+
+ return false;
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/services/JobRegistryService.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/services/JobRegistryService.java b/api/execution/src/main/java/org/apache/edgent/execution/services/JobRegistryService.java
new file mode 100644
index 0000000..7f6795c
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/services/JobRegistryService.java
@@ -0,0 +1,126 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+package org.apache.edgent.execution.services;
+
+import java.util.Set;
+
+import org.apache.edgent.execution.Job;
+import org.apache.edgent.function.BiConsumer;
+
+/**
+ * Job registry service.
+ * <p>
+ * Keeps the list of {@link Job} instances registered by the runtime and
+ * provides the necessary methods to register and remove jobs, access
+ * registered jobs, as well as register listeners which are notified on job
+ * registrations, removals, and updates.
+ * The following event types are sent to registered listeners:
+ * </p>
+ * <ul>
+ * <li>An {@link EventType#ADD} event is sent when a job is added.</li>
+ * <li>An {@link EventType#REMOVE} event is sent when a job is removed.</li>
+ * <li>An {@link EventType#UPDATE} event is sent when a job is updated.</li>
+ * </ul>
+ * <h3>Event dispatch</h3>
+ * If a listener invocation throws an Exception, then the exception
+ * will not prevent the remaining listeners from being invoked. However,
+ * if the invocation throws an Error, then it is recommended that
+ * the event dispatch stop.
+ */
+public interface JobRegistryService {
+ /**
+ * Job event types.
+ */
+ enum EventType {
+ /** A Job has been added to the registry. */
+ ADD,
+ /** A Job has been removed from the registry. */
+ REMOVE,
+ /** A registered Job has been updated. */
+ UPDATE
+ }
+
+ /**
+ * Adds a handler to a collection of listeners that will be notified
+ * on job registration and state changes. Listeners will be notified
+ * in the order in which they are added.
+ * <p>
+ * A listener is notified of all existing jobs when it is first added.
+ *
+ * @param listener the listener that will be added
+ * @throws IllegalArgumentException if the listener parameter is
+ * {@code null}
+ */
+ void addListener(BiConsumer<JobRegistryService.EventType, Job> listener)
+ throws IllegalArgumentException;
+
+ /**
+ * Removes a handler from this registry's collection of listeners.
+ *
+ * @param listener the listener that will be removed
+ * @return whether or not the listener has been removed
+ */
+ boolean removeListener(
+ BiConsumer<JobRegistryService.EventType, Job> listener);
+
+ /**
+ * Returns a set of all the registered job identifiers.
+ *
+ * @return the identifiers of all the jobs
+ */
+ Set<String> getJobIds();
+
+ /**
+ * Returns a job given its identifier.
+ *
+ * @param id job identifier
+ * @return the job or {@code null} if no job is registered with that
+ * identifier.
+ */
+ Job getJob(String id);
+
+ /**
+ * Adds the specified job.
+ *
+ * @param job the job to register
+ *
+ * @throws IllegalArgumentException if a job is null, or if a job with
+ * the same identifier is already registered
+ */
+ void addJob(Job job) throws IllegalArgumentException;
+
+ /**
+ * Removes the job specified by the given identifier.
+ *
+ * @param jobId the identifier of the job to remove
+ * @return whether or not the job was removed
+ */
+ boolean removeJob(String jobId);
+
+ /**
+ * Notifies listeners that the specified registered job has
+ * been updated.
+ *
+ * @param job the job
+ * @return whether or not the job was found in the registry
+ */
+ boolean updateJob(Job job);
+
+ // TODO add job retrieval given its name
+}
http://git-wip-us.apache.org/repos/asf/incubator-quarks/blob/a129aa16/api/execution/src/main/java/org/apache/edgent/execution/services/RuntimeServices.java
----------------------------------------------------------------------
diff --git a/api/execution/src/main/java/org/apache/edgent/execution/services/RuntimeServices.java b/api/execution/src/main/java/org/apache/edgent/execution/services/RuntimeServices.java
new file mode 100644
index 0000000..b5d2c39
--- /dev/null
+++ b/api/execution/src/main/java/org/apache/edgent/execution/services/RuntimeServices.java
@@ -0,0 +1,74 @@
+/*
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+*/
+package org.apache.edgent.execution.services;
+
+/**
+ * At runtime a container provides services to
+ * executing elements such as oplets and functions.
+ *
+ * <P>
+ * Services, providers and applications can optionally store
+ * preferences (configuration information) using a {@code java.util.pref.Preferences}
+ * instance registered as a service. Any provider may optionally register
+ * a root {@code Preferences} node. Once a provider registers
+ * a {@code Preferences} node, preferences will
+ * be saved across reboots of the provider and/or JVM if the underlying
+ * {@code Preferences} implementation supports it.
+ *
+ * <BR>
+ * Services and application code can store keys
+ * in the root {@code Preferences} node or create child nodes
+ * as required.
+ * <pre>
+ * <code>
+ * Preferences prefs = rs.getService(Preferences.class);
+ * if (prefs != null) {
+ * prefs.put("threshold", 3);
+ * }
+ * </code>
+ * </pre>
+ * </P>
+ *
+ */
+public interface RuntimeServices {
+
+ /**
+ * Get a service for this invocation.
+ * <P>
+ * These services must be provided by all implementations:
+ * </P>
+ * <UL>
+ * <LI>
+ * {@code java.util.concurrent.ThreadFactory} - Thread factory, runtime code should
+ * create new threads using this factory.
+ * </LI>
+ * <LI>
+ * {@code java.util.concurrent.ScheduledExecutorService} - Scheduler, runtime code should
+ * execute asynchronous and repeating tasks using this scheduler.
+ * </LI>
+ * </UL>
+ *
+ * @param <T> service class type
+ * @param serviceClass Type of the service required.
+ * @return Service of type implementing {@code serviceClass} if the
+ * container this invocation runs in supports that service,
+ * otherwise {@code null}.
+ */
+ <T> T getService(Class<T> serviceClass);
+}