You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@twill.apache.org by ch...@apache.org on 2013/12/13 23:27:37 UTC
[21/28] [TWILL-14] Bootstrapping for the site generation.
Reorganization of the source tree happens:
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index 0c8bc43..ea7bc90 100644
--- a/pom.xml
+++ b/pom.xml
@@ -25,18 +25,127 @@
<artifactId>twill-parent</artifactId>
<version>0.1.0-SNAPSHOT</version>
<packaging>pom</packaging>
- <name>Twill library parent project</name>
+ <name>Apache Twill</name>
+ <url>http://twill.incubator.apache.org</url>
+
+ <developers>
+ <developer>
+ <id>vinodkv</id>
+ <name>Vinod K</name>
+ <email>vinodkv@apache.org</email>
+ <roles>
+ <role>Mentor</role>
+ </roles>
+ </developer>
+ <developer>
+ <id>tomwhite</id>
+ <name>Thomas White</name>
+ <email>tomwhite@apache.org</email>
+ <roles>
+ <role>Mentor</role>
+ </roles>
+ </developer>
+ <developer>
+ <id>phunt</id>
+ <name>Patrick Hunt</name>
+ <email>phuntv@apache.org</email>
+ <roles>
+ <role>Mentor</role>
+ </roles>
+ </developer>
+ <developer>
+ <id>acmurthy</id>
+ <name>Arun C Murthy</name>
+ <email>acmurthyu@apache.org</email>
+ <roles>
+ <role>Mentor</role>
+ </roles>
+ </developer>
+ <developer>
+ <id>asavu</id>
+ <name>Andrei Savu</name>
+ <email>asavu@apache.org</email>
+ <roles>
+ <role>Mentor</role>
+ </roles>
+ </developer>
+ <developer>
+ <id>chtyim</id>
+ <name>Terence Yim</name>
+ <email>chtyim@apache.org</email>
+ <roles>
+ <role>Committer</role>
+ </roles>
+ </developer>
+ <developer>
+ <id>anew</id>
+ <name>Andreas Neumann</name>
+ <email>anew@apache.org</email>
+ <roles>
+ <role>Committer</role>
+ </roles>
+ </developer>
+ <developer>
+ <id>garyh</id>
+ <name>Gary Helmling</name>
+ <email>garyh@apache.org</email>
+ <roles>
+ <role>Committer</role>
+ </roles>
+ </developer>
+ <developer>
+ <name>Albert Shau</name>
+ <email>albert.shau@yahoo.com</email>
+ <roles>
+ <role>Committer</role>
+ </roles>
+ </developer>
+ <developer>
+ <name>Poorna Chandra</name>
+ <email>poornachandra@gmail.com</email>
+ <roles>
+ <role>Committer</role>
+ </roles>
+ </developer>
+ </developers>
<modules>
- <module>common</module>
- <module>discovery-api</module>
- <module>api</module>
- <module>zookeeper</module>
- <module>discovery-core</module>
- <module>core</module>
- <module>yarn</module>
+ <module>twill-common</module>
+ <module>twill-discovery-api</module>
+ <module>twill-api</module>
+ <module>twill-zookeeper</module>
+ <module>twill-discovery-core</module>
+ <module>twill-core</module>
+ <module>twill-yarn</module>
</modules>
+
+ <issueManagement>
+ <url>https://issues.apache.org/jira/browse/TWILL</url>
+ </issueManagement>
+ <mailingLists>
+ <mailingList>
+ <name>Development</name>
+ <post>dev@twill.incubator.apache.org</post>
+ <subscribe>dev-subscribe@twill.incubator.apache.org</subscribe>
+ <unsubscribe>dev-unsubscribe@twill.incubator.apache.org</unsubscribe>
+ <archive>http://mail-archives.apache.org/mod_mbox/twill-dev/</archive>
+ <otherArchives>
+ <otherArchive>http://twill-dev.markmail.org</otherArchive>
+ </otherArchives>
+ </mailingList>
+ <mailingList>
+ <name>Commits</name>
+ <post>commits@twill.incubator.apache.org</post>
+ <subscribe>commits-subscribe@twill.incubator.apache.org</subscribe>
+ <unsubscribe>commits-unsubscribe@twill.incubator.apache.org</unsubscribe>
+ <archive>http://mail-archives.apache.org/mod_mbox/twill-commits/</archive>
+ <otherArchives>
+ <otherArchive>http://twill-comits.markmail.org</otherArchive>
+ </otherArchives>
+ </mailingList>
+ </mailingLists>
+
<repositories>
<repository>
<id>cloudera-releases</id>
@@ -137,7 +246,14 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
- <version>3.2</version>
+ <version>3.3</version>
+ <dependencies>
+ <dependency>
+ <groupId>org.apache.maven.doxia</groupId>
+ <artifactId>doxia-module-markdown</artifactId>
+ <version>1.3</version>
+ </dependency>
+ </dependencies>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
@@ -548,6 +664,56 @@
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-project-info-reports-plugin</artifactId>
+ <version>2.7</version>
+ <reportSets>
+ <reportSet>
+ <reports/>
+ </reportSet>
+ <reportSet>
+ <id>aggregate</id>
+ <inherited>false</inherited>
+ <reports>
+ <report>index</report>
+ <report>mailing-list</report>
+ <report>scm</report>
+ <report>issue-tracking</report>
+ <report>project-team</report>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <version>2.9</version>
+ <configuration>
+ <failOnError>false</failOnError>
+ <excludePackageNames>*.internal.*</excludePackageNames>
+ <links>
+ <link>http://download.oracle.com/javase/6/docs/api/</link>
+ </links>
+ <bottom>
+ <![CDATA[Copyright © 2013 <a href="http://www.apache.org">The Apache Software Foundation</a>. All rights reserved.]]>
+ </bottom>
+ </configuration>
+ <reportSets>
+ <reportSet>
+ <reports>
+ <report>javadoc</report>
+ </reports>
+ </reportSet>
+ <reportSet>
+ <id>aggregate</id>
+ <inherited>false</inherited>
+ <reports>
+ <report>aggregate</report>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-report-plugin</artifactId>
<version>2.14.1</version>
</plugin>
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/src/site/markdown/GettingStarted.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/GettingStarted.md b/src/site/markdown/GettingStarted.md
new file mode 100644
index 0000000..c8384a3
--- /dev/null
+++ b/src/site/markdown/GettingStarted.md
@@ -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.
+-->
+
+
+<head>
+ <title>Getting started</title>
+</head>
+
+### Clone and build the Twill library
+
+```sh
+$ git clone https://git-wip-us.apache.org/repos/asf/incubator-twill.git twill
+$ cd twill
+$ mvn clean install
+```
+
+### Quick example
+
+Let's begin by building a basic `EchoServer` in Twill. Traditionally, when you build a server as simple as this,
+you add logic within a `Runnable` implementation to run it in a `Thread` using an appropriate `ExecutorService`:
+
+```java
+public class EchoServer implements Runnable {
+ private static Logger LOG = LoggerFactory.getLogger(EchoServer.class);
+ private final ServerSocket serverSocket;
+
+ public EchoServer() {
+ ...
+ }
+
+ @Override
+ public void run() {
+ while ( isRunning() ) {
+ Socket socket = serverSocket.accept();
+ ...
+ }
+ }
+}
+```
+
+Our example defines an implementation of `Runnable` that implements the `run()` method.
+The `EchoServer` is now a `Runnable` that can be executed by an `ExecutorService`:
+
+```java
+ExecutorService service = Executors.newFixedThreadPool(2);
+service.submit(new EchoServer());
+```
+
+The above model is familiar, but now assume you want to run your `EchoServer` on a YARN cluster.
+To do this, all you need to do is implement the `TwillRunnable` interface similarly to how you
+normally implement `Runnable`:
+
+```java
+public class EchoServer implements TwillRunnable {
+
+ private static Logger LOG = LoggerFactory.getLogger(EchoServer.class);
+ private final ServerSocket serverSocket;
+ private final int port;
+
+ public EchoServer() {
+ ...
+ }
+
+ @Override
+ public void run() {
+ while ( isRunning() ) {
+ Socket socket = serverSocket.accept();
+ ...
+ }
+ }
+}
+```
+
+To run `EchoServer` on the YARN cluster, you need a `TwillRunnerService`, which is similar to `ExecutorService`.
+You can specify the YARN cluster configuration and connection string to a running instance of a Zookeeper service
+to create an instance of `TwillRunnerService`:
+
+```java
+TwillRunnerService runnerService = new YarnTwillRunnerService(
+ new YarnConfiguration(), zkConnectStr);
+runnerService.startAndWait();
+```
+
+Now you are read to run the EchoServer on YARN, by simply preparing and starting through the `TwillRunnerService`. You
+can also attach log handler to receives logs generated by EchoService running on some nodes in the cluster:
+
+```java
+TwillController controller = runnerService.prepare(new EchoServer())
+ .addLogHandler(new PrinterLogHandler(new PrintWriter(System.out)))
+ .start();
+```
+
+Now that the `EchoServer` is started and you can inspect or control the application through the `TwillController`.
+For example, you can attach listeners for state changes:
+
+```java
+controller.addListener(new ListenerAdapter() {
+ @Override
+ public void running() {
+ LOG.info('Echo Server Started');
+ }
+}
+```
+
+You can also stop the application through the `TwillController`:
+
+```java
+controller.stop().get();
+```
+
+This will shut down the application master and all the containers.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/src/site/markdown/index.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
new file mode 100644
index 0000000..06eb967
--- /dev/null
+++ b/src/site/markdown/index.md
@@ -0,0 +1,27 @@
+<!--
+ 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.
+-->
+
+<head>
+ <title>Home</title>
+</head>
+
+### What is Twill?
+
+Twill is an abstraction over Apache Hadoop® YARN that reduces the complexity of developing distributed applications,
+allowing developers to focus more on their business logic. Twill allows you to use YARN’s distributed capabilities
+with a programming model that is similar to running threads.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
new file mode 100644
index 0000000..c400c01
--- /dev/null
+++ b/src/site/site.xml
@@ -0,0 +1,82 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!--
+ 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.
+-->
+<project name="Apache Twill">
+ <bannerRight>
+ <src>http://incubator.apache.org/images/egg-logo.png</src>
+ <href>http://incubator.apache.org/</href>
+ </bannerRight>
+
+ <publishDate position="none"/>
+ <version position="none"/>
+
+ <skin>
+ <groupId>org.apache.maven.skins</groupId>
+ <artifactId>maven-fluido-skin</artifactId>
+ <version>1.3.0</version>
+ </skin>
+
+ <body>
+
+ <breadcrumbs position="left">
+ <item name="Apache Twill" href="http://twill.incubator.apache.org/"/>
+ </breadcrumbs>
+
+ <menu name="Apache Twill">
+ <item name="Introduction" href="./index.html"/>
+ <item name="Getting Started" href="./GettingStarted.html"/>
+ <item name="API documentations" href="./apidocs/index.html"/>
+ </menu>
+
+ <menu name="Get Involved">
+ <item name="Mailing Lists" href="mail-lists.html"/>
+ <item name="Sources" href="source-repository.html"/>
+ <item name="Issues" href="issue-tracking.html"/>
+ <item name="Team" href="team-list.html"/>
+ </menu>
+
+ <menu name="ASF">
+ <item name="Apache Incubator" href="http://incubator.apache.org/"/>
+ <item name="Apache Foundation" href="http://www.apache.org/foundation/"/>
+ <item name="How Apache Works" href="http://www.apache.org/foundation/how-it-works.html"/>
+ <item name="The Apache License" href="http://www.apache.org/licenses/LICENSE-2.0.html"/>
+ <item name="Sponsoring Apache" href="http://www.apache.org/foundation/sponsorship.html"/>
+ <item name="Thanks" href="http://www.apache.org/foundation/thanks.html"/>
+ </menu>
+
+ <footer>
+ <div class="row span16">
+ Apache Twill, Apache, the Apache feather logo,
+ and the Apache Twill project logos are trademarks of The Apache Software Foundation.
+ All other marks mentioned may be trademarks or registered trademarks of their respective owners.
+ <a href="${project.url}/privacy-policy.html">Privacy Policy</a>
+ </div>
+ </footer>
+ </body>
+
+ <custom>
+ <fluidoSkin>
+ <topBarEnabled>true</topBarEnabled>
+ <navBarStyle>navbar-inverse</navBarStyle>
+ <sideBarEnabled>true</sideBarEnabled>
+ <leftColumnClass>span2</leftColumnClass>
+ <bodyColumnClass>span10</bodyColumnClass>
+ </fluidoSkin>
+ </custom>
+
+</project>
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/pom.xml
----------------------------------------------------------------------
diff --git a/twill-api/pom.xml b/twill-api/pom.xml
new file mode 100644
index 0000000..49b92c8
--- /dev/null
+++ b/twill-api/pom.xml
@@ -0,0 +1,54 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ 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.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <modelVersion>4.0.0</modelVersion>
+
+ <parent>
+ <groupId>org.apache.twill</groupId>
+ <artifactId>twill-parent</artifactId>
+ <version>0.1.0-SNAPSHOT</version>
+ </parent>
+
+ <artifactId>twill-api</artifactId>
+ <packaging>jar</packaging>
+ <name>Twill API</name>
+
+ <dependencies>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>twill-common</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>${project.groupId}</groupId>
+ <artifactId>twill-discovery-api</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>com.google.guava</groupId>
+ <artifactId>guava</artifactId>
+ </dependency>
+ <dependency>
+ <groupId>com.google.code.findbugs</groupId>
+ <artifactId>jsr305</artifactId>
+ </dependency>
+ </dependencies>
+</project>
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/AbstractTwillRunnable.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/AbstractTwillRunnable.java b/twill-api/src/main/java/org/apache/twill/api/AbstractTwillRunnable.java
new file mode 100644
index 0000000..67cec0a
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/AbstractTwillRunnable.java
@@ -0,0 +1,75 @@
+/*
+ * 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.twill.api;
+
+import com.google.common.collect.ImmutableMap;
+
+import java.util.Map;
+
+/**
+ * This abstract class provides default implementation of the {@link TwillRunnable}.
+ */
+public abstract class AbstractTwillRunnable implements TwillRunnable {
+
+ private Map<String, String> args;
+ private TwillContext context;
+
+ protected AbstractTwillRunnable() {
+ this.args = ImmutableMap.of();
+ }
+
+ protected AbstractTwillRunnable(Map<String, String> args) {
+ this.args = ImmutableMap.copyOf(args);
+ }
+
+ @Override
+ public TwillRunnableSpecification configure() {
+ return TwillRunnableSpecification.Builder.with()
+ .setName(getClass().getSimpleName())
+ .withConfigs(args)
+ .build();
+ }
+
+ @Override
+ public void initialize(TwillContext context) {
+ this.context = context;
+ this.args = context.getSpecification().getConfigs();
+ }
+
+ @Override
+ public void handleCommand(org.apache.twill.api.Command command) throws Exception {
+ // No-op by default. Left for children class to override.
+ }
+
+ @Override
+ public void destroy() {
+ // No-op by default. Left for children class to override.
+ }
+
+ protected Map<String, String> getArguments() {
+ return args;
+ }
+
+ protected String getArgument(String key) {
+ return args.get(key);
+ }
+
+ protected TwillContext getContext() {
+ return context;
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/Command.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/Command.java b/twill-api/src/main/java/org/apache/twill/api/Command.java
new file mode 100644
index 0000000..b23b3a8
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/Command.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.twill.api;
+
+import com.google.common.base.Objects;
+import com.google.common.base.Preconditions;
+import com.google.common.collect.ImmutableMap;
+
+import java.util.Map;
+
+/**
+ * Represents command objects.
+ */
+public interface Command {
+
+ String getCommand();
+
+ Map<String, String> getOptions();
+
+ /**
+ * Builder for creating {@link Command} object.
+ */
+ static final class Builder {
+
+ private final String command;
+ private final ImmutableMap.Builder<String, String> options = ImmutableMap.builder();
+
+ public static Builder of(String command) {
+ Preconditions.checkArgument(command != null, "Command cannot be null.");
+ return new Builder(command);
+ }
+
+ public Builder addOption(String key, String value) {
+ options.put(key, value);
+ return this;
+ }
+
+ public Builder addOptions(Map<String, String> map) {
+ options.putAll(map);
+ return this;
+ }
+
+ public Command build() {
+ return new SimpleCommand(command, options.build());
+ }
+
+ private Builder(String command) {
+ this.command = command;
+ }
+
+ /**
+ * Simple implementation of {@link org.apache.twill.api.Command}.
+ */
+ private static final class SimpleCommand implements Command {
+ private final String command;
+ private final Map<String, String> options;
+
+ SimpleCommand(String command, Map<String, String> options) {
+ this.command = command;
+ this.options = options;
+ }
+
+ @Override
+ public String getCommand() {
+ return command;
+ }
+
+ @Override
+ public Map<String, String> getOptions() {
+ return options;
+ }
+
+ @Override
+ public int hashCode() {
+ return Objects.hashCode(command, options);
+ }
+
+ @Override
+ public String toString() {
+ return Objects.toStringHelper(Command.class)
+ .add("command", command)
+ .add("options", options)
+ .toString();
+ }
+
+ @Override
+ public boolean equals(Object obj) {
+ if (obj == this) {
+ return true;
+ }
+ if (!(obj instanceof Command)) {
+ return false;
+ }
+ Command other = (Command) obj;
+ return command.equals(other.getCommand()) && options.equals(other.getOptions());
+ }
+ }
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/EventHandler.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/EventHandler.java b/twill-api/src/main/java/org/apache/twill/api/EventHandler.java
new file mode 100644
index 0000000..ede5b65
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/EventHandler.java
@@ -0,0 +1,146 @@
+/*
+ * 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.twill.api;
+
+import com.google.common.collect.ImmutableMap;
+
+import java.util.Map;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * A callback handler for acting on application events related to {@link TwillRunnable} lifecycle events.
+ */
+public abstract class EventHandler {
+
+ protected EventHandlerContext context;
+
+ /**
+ * Represents action to act upon runnable launch timeout.
+ */
+ public static final class TimeoutAction {
+
+ // Next timeout in milliseconds.
+ private final long timeout;
+
+ /**
+ * Creates a {@link TimeoutAction} to indicate aborting the application.
+ */
+ public static TimeoutAction abort() {
+ return new TimeoutAction(-1);
+ }
+
+ /**
+ * Creates a {@link TimeoutAction} to indicate recheck again after the given time has passed.
+ * @param elapse Time to elapse before checking for the timeout again.
+ * @param unit Unit of the elapse time.
+ */
+ public static TimeoutAction recheck(long elapse, TimeUnit unit) {
+ return new TimeoutAction(TimeUnit.MILLISECONDS.convert(elapse, unit));
+ }
+
+ private TimeoutAction(long timeout) {
+ this.timeout = timeout;
+ }
+
+ /**
+ * Returns timeout in milliseconds or {@code -1} if to abort the application.
+ */
+ public long getTimeout() {
+ return timeout;
+ }
+ }
+
+ /**
+ * This class holds information about a launch timeout event.
+ */
+ public static final class TimeoutEvent {
+ private final String runnableName;
+ private final int expectedInstances;
+ private final int actualInstances;
+ private final long requestTime;
+
+ public TimeoutEvent(String runnableName, int expectedInstances, int actualInstances, long requestTime) {
+ this.runnableName = runnableName;
+ this.expectedInstances = expectedInstances;
+ this.actualInstances = actualInstances;
+ this.requestTime = requestTime;
+ }
+
+ public String getRunnableName() {
+ return runnableName;
+ }
+
+ public int getExpectedInstances() {
+ return expectedInstances;
+ }
+
+ public int getActualInstances() {
+ return actualInstances;
+ }
+
+ public long getRequestTime() {
+ return requestTime;
+ }
+ }
+
+ /**
+ * Returns an {@link EventHandlerSpecification} for configuring this handler class.
+ */
+ public EventHandlerSpecification configure() {
+ return new EventHandlerSpecification() {
+ @Override
+ public String getClassName() {
+ return EventHandler.this.getClass().getName();
+ }
+
+ @Override
+ public Map<String, String> getConfigs() {
+ return EventHandler.this.getConfigs();
+ }
+ };
+ }
+
+ /**
+ * Invoked by the application to initialize this EventHandler instance.
+ * @param context
+ */
+ public void initialize(EventHandlerContext context) {
+ this.context = context;
+ }
+
+ /**
+ * Invoked by the application when shutting down.
+ */
+ public void destroy() {
+ // No-op
+ }
+
+ /**
+ * Invoked when the number of expected instances doesn't match with number of actual instances.
+ * @param timeoutEvents An Iterable of {@link TimeoutEvent} that contains information about runnable launch timeout.
+ * @return A {@link TimeoutAction} to govern action to act.
+ */
+ public abstract TimeoutAction launchTimeout(Iterable<TimeoutEvent> timeoutEvents);
+
+ /**
+ * Returns set of configurations available at runtime for access.
+ */
+ protected Map<String, String> getConfigs() {
+ return ImmutableMap.of();
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/EventHandlerContext.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/EventHandlerContext.java b/twill-api/src/main/java/org/apache/twill/api/EventHandlerContext.java
new file mode 100644
index 0000000..8e58af6
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/EventHandlerContext.java
@@ -0,0 +1,26 @@
+/*
+ * 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.twill.api;
+
+/**
+ * Represents runtime context for {@link EventHandler}.
+ */
+public interface EventHandlerContext {
+
+ EventHandlerSpecification getSpecification();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/EventHandlerSpecification.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/EventHandlerSpecification.java b/twill-api/src/main/java/org/apache/twill/api/EventHandlerSpecification.java
new file mode 100644
index 0000000..190f222
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/EventHandlerSpecification.java
@@ -0,0 +1,30 @@
+/*
+ * 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.twill.api;
+
+import java.util.Map;
+
+/**
+ * Specification for {@link EventHandler}.
+ */
+public interface EventHandlerSpecification {
+
+ String getClassName();
+
+ Map<String, String> getConfigs();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/LocalFile.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/LocalFile.java b/twill-api/src/main/java/org/apache/twill/api/LocalFile.java
new file mode 100644
index 0000000..df35a3b
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/LocalFile.java
@@ -0,0 +1,46 @@
+/*
+ * 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.twill.api;
+
+import javax.annotation.Nullable;
+import java.net.URI;
+
+/**
+ * This interface represents a local file that will be available for the container running a {@link TwillRunnable}.
+ */
+public interface LocalFile {
+
+ String getName();
+
+ URI getURI();
+
+ /**
+ * Returns the the last modified time of the file or {@code -1} if unknown.
+ */
+ long getLastModified();
+
+ /**
+ * Returns the size of the file or {@code -1} if unknown.
+ */
+ long getSize();
+
+ boolean isArchive();
+
+ @Nullable
+ String getPattern();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/ResourceReport.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/ResourceReport.java b/twill-api/src/main/java/org/apache/twill/api/ResourceReport.java
new file mode 100644
index 0000000..0d63378
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/ResourceReport.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.twill.api;
+
+import java.util.Collection;
+import java.util.Map;
+
+/**
+ * This interface provides a snapshot of the resources an application is using
+ * broken down by each runnable.
+ */
+public interface ResourceReport {
+ /**
+ * Get all the run resources being used by all instances of the specified runnable.
+ *
+ * @param runnableName the runnable name.
+ * @return resources being used by all instances of the runnable.
+ */
+ public Collection<TwillRunResources> getRunnableResources(String runnableName);
+
+ /**
+ * Get all the run resources being used across all runnables.
+ *
+ * @return all run resources used by all instances of all runnables.
+ */
+ public Map<String, Collection<TwillRunResources>> getResources();
+
+ /**
+ * Get the resources application master is using.
+ *
+ * @return resources being used by the application master.
+ */
+ public TwillRunResources getAppMasterResources();
+
+ /**
+ * Get the id of the application master.
+ *
+ * @return id of the application master.
+ */
+ public String getApplicationId();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/ResourceSpecification.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/ResourceSpecification.java b/twill-api/src/main/java/org/apache/twill/api/ResourceSpecification.java
new file mode 100644
index 0000000..b40682f
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/ResourceSpecification.java
@@ -0,0 +1,152 @@
+/*
+ * 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.twill.api;
+
+import org.apache.twill.internal.DefaultResourceSpecification;
+
+/**
+ * This interface provides specifications for resource requirements including set and get methods for number of cores, amount of memory, and number of instances.
+ */
+public interface ResourceSpecification {
+
+ final ResourceSpecification BASIC = Builder.with().setVirtualCores(1).setMemory(512, SizeUnit.MEGA).build();
+
+ /**
+ * Unit for specifying memory size.
+ */
+ enum SizeUnit {
+ MEGA(1),
+ GIGA(1024);
+
+ private final int multiplier;
+
+ private SizeUnit(int multiplier) {
+ this.multiplier = multiplier;
+ }
+ }
+
+ /**
+ * Returns the number of virtual CPU cores. DEPRECATED, use getVirtualCores instead.
+ * @return Number of virtual CPU cores.
+ */
+ @Deprecated
+ int getCores();
+
+ /**
+ * Returns the number of virtual CPU cores.
+ * @return Number of virtual CPU cores.
+ */
+ int getVirtualCores();
+
+ /**
+ * Returns the memory size in MB.
+ * @return Memory size
+ */
+ int getMemorySize();
+
+ /**
+ * Returns the uplink bandwidth in Mbps.
+ * @return Uplink bandwidth or -1 representing unlimited bandwidth.
+ */
+ int getUplink();
+
+ /**
+ * Returns the downlink bandwidth in Mbps.
+ * @return Downlink bandwidth or -1 representing unlimited bandwidth.
+ */
+ int getDownlink();
+
+ /**
+ * Returns number of execution instances.
+ * @return Number of execution instances.
+ */
+ int getInstances();
+
+ /**
+ * Builder for creating {@link ResourceSpecification}.
+ */
+ static final class Builder {
+
+ private int cores;
+ private int memory;
+ private int uplink = -1;
+ private int downlink = -1;
+ private int instances = 1;
+
+ public static CoreSetter with() {
+ return new Builder().new CoreSetter();
+ }
+
+ public final class CoreSetter {
+ @Deprecated
+ public MemorySetter setCores(int cores) {
+ Builder.this.cores = cores;
+ return new MemorySetter();
+ }
+
+ public MemorySetter setVirtualCores(int cores) {
+ Builder.this.cores = cores;
+ return new MemorySetter();
+ }
+ }
+
+ public final class MemorySetter {
+ public AfterMemory setMemory(int size, SizeUnit unit) {
+ Builder.this.memory = size * unit.multiplier;
+ return new AfterMemory();
+ }
+ }
+
+ public final class AfterMemory extends Build {
+ public AfterInstances setInstances(int instances) {
+ Builder.this.instances = instances;
+ return new AfterInstances();
+ }
+ }
+
+ public final class AfterInstances extends Build {
+ public AfterUplink setUplink(int uplink, SizeUnit unit) {
+ Builder.this.uplink = uplink * unit.multiplier;
+ return new AfterUplink();
+ }
+ }
+
+ public final class AfterUplink extends Build {
+ public AfterDownlink setDownlink(int downlink, SizeUnit unit) {
+ Builder.this.downlink = downlink * unit.multiplier;
+ return new AfterDownlink();
+ }
+ }
+
+ public final class AfterDownlink extends Build {
+
+ @Override
+ public ResourceSpecification build() {
+ return super.build();
+ }
+ }
+
+ public abstract class Build {
+ public ResourceSpecification build() {
+ return new DefaultResourceSpecification(cores, memory, instances, uplink, downlink);
+ }
+ }
+
+ private Builder() {}
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/RunId.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/RunId.java b/twill-api/src/main/java/org/apache/twill/api/RunId.java
new file mode 100644
index 0000000..7f3c4fe
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/RunId.java
@@ -0,0 +1,26 @@
+/*
+ * 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.twill.api;
+
+/**
+ * Represents the unique ID of a particular execution.
+ */
+public interface RunId {
+
+ String getId();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/RuntimeSpecification.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/RuntimeSpecification.java b/twill-api/src/main/java/org/apache/twill/api/RuntimeSpecification.java
new file mode 100644
index 0000000..99e11a4
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/RuntimeSpecification.java
@@ -0,0 +1,34 @@
+/*
+ * 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.twill.api;
+
+import java.util.Collection;
+
+/**
+ * Specifications for runtime requirements.
+ */
+public interface RuntimeSpecification {
+
+ String getName();
+
+ TwillRunnableSpecification getRunnableSpecification();
+
+ ResourceSpecification getResourceSpecification();
+
+ Collection<LocalFile> getLocalFiles();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/SecureStore.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/SecureStore.java b/twill-api/src/main/java/org/apache/twill/api/SecureStore.java
new file mode 100644
index 0000000..707a152
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/SecureStore.java
@@ -0,0 +1,26 @@
+/*
+ * 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.twill.api;
+
+/**
+ * Represents storage of secure tokens.
+ */
+public interface SecureStore {
+
+ <T> T getStore();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/SecureStoreUpdater.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/SecureStoreUpdater.java b/twill-api/src/main/java/org/apache/twill/api/SecureStoreUpdater.java
new file mode 100644
index 0000000..5912247
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/SecureStoreUpdater.java
@@ -0,0 +1,33 @@
+/*
+ * 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.twill.api;
+
+/**
+ * Represents class capable of creating update of {@link SecureStore} for live applications.
+ */
+public interface SecureStoreUpdater {
+
+ /**
+ * Invoked when an update to SecureStore is needed.
+ *
+ * @param application The name of the application.
+ * @param runId The runId of the live application.
+ * @return A new {@link SecureStore}.
+ */
+ SecureStore update(String application, RunId runId);
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/ServiceAnnouncer.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/ServiceAnnouncer.java b/twill-api/src/main/java/org/apache/twill/api/ServiceAnnouncer.java
new file mode 100644
index 0000000..d8e4358
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/ServiceAnnouncer.java
@@ -0,0 +1,33 @@
+/*
+ * 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.twill.api;
+
+import org.apache.twill.common.Cancellable;
+
+/**
+ * This interface provides a way to announce the availability of a service.
+ */
+public interface ServiceAnnouncer {
+
+ /**
+ * Registers an endpoint that could be discovered by external party.
+ * @param serviceName Name of the endpoint
+ * @param port Port of the endpoint.
+ */
+ Cancellable announce(String serviceName, int port);
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/ServiceController.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/ServiceController.java b/twill-api/src/main/java/org/apache/twill/api/ServiceController.java
new file mode 100644
index 0000000..0ea64f9
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/ServiceController.java
@@ -0,0 +1,70 @@
+/*
+ * 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.twill.api;
+
+import com.google.common.util.concurrent.ListenableFuture;
+import com.google.common.util.concurrent.Service;
+
+import java.util.concurrent.Executor;
+
+/**
+ * This interface is for controlling a remote running service.
+ */
+public interface ServiceController extends Service {
+
+ /**
+ * Returns the {@link RunId} of the running application.
+ */
+ RunId getRunId();
+
+ /**
+ * Sends a user command to the running application.
+ * @param command The command to send.
+ * @return A {@link ListenableFuture} that will be completed when the command is successfully processed
+ * by the target application.
+ */
+ ListenableFuture<Command> sendCommand(Command command);
+
+ /**
+ * Sends a user command to the given runnable of the running application.
+ * @param runnableName Name of the {@link TwillRunnable}.
+ * @param command The command to send.
+ * @return A {@link ListenableFuture} that will be completed when the command is successfully processed
+ * by the target runnable.
+ */
+ ListenableFuture<Command> sendCommand(String runnableName, Command command);
+
+ /**
+ * Requests to forcefully kill a running service.
+ */
+ void kill();
+
+ /**
+ * Registers a {@link Listener} to be {@linkplain Executor#execute executed} on the given
+ * executor. The listener will have the corresponding transition method called whenever the
+ * service changes state. When added, the current state of the service will be reflected through
+ * callback to the listener. Methods on the listener is guaranteed to be called no more than once.
+ *
+ * @param listener the listener to run when the service changes state is complete
+ * @param executor the executor in which the the listeners callback methods will be run. For fast,
+ * lightweight listeners that would be safe to execute in any thread, consider
+ * {@link com.google.common.util.concurrent.MoreExecutors#sameThreadExecutor}.
+ */
+ @Override
+ void addListener(Listener listener, Executor executor);
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/TwillApplication.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/TwillApplication.java b/twill-api/src/main/java/org/apache/twill/api/TwillApplication.java
new file mode 100644
index 0000000..b49e7a7
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/TwillApplication.java
@@ -0,0 +1,30 @@
+/*
+ * 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.twill.api;
+
+/**
+ * Represents a application that can be launched by Twill.
+ */
+public interface TwillApplication {
+
+ /**
+ * Invoked when launching the application on the client side.
+ * @return A {@link TwillSpecification} specifying properties about this application.
+ */
+ TwillSpecification configure();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/TwillContext.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/TwillContext.java b/twill-api/src/main/java/org/apache/twill/api/TwillContext.java
new file mode 100644
index 0000000..b4ddb6e
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/TwillContext.java
@@ -0,0 +1,76 @@
+/*
+ * 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.twill.api;
+
+import java.net.InetAddress;
+
+/**
+ * Represents the runtime context of a {@link TwillRunnable}.
+ */
+public interface TwillContext extends ServiceAnnouncer {
+
+ /**
+ * Returns the {@link RunId} of this running instance of {@link TwillRunnable}.
+ */
+ RunId getRunId();
+
+ /**
+ * Returns the {@link RunId} of this running application.
+ */
+ RunId getApplicationRunId();
+
+ /**
+ * Returns the number of running instances assigned for this {@link TwillRunnable}.
+ */
+ int getInstanceCount();
+
+ /**
+ * Returns the hostname that the runnable is running on.
+ */
+ InetAddress getHost();
+
+ /**
+ * Returns the runtime arguments that are passed to the {@link TwillRunnable}.
+ */
+ String[] getArguments();
+
+ /**
+ * Returns the runtime arguments that are passed to the {@link TwillApplication}.
+ */
+ String[] getApplicationArguments();
+
+ /**
+ * Returns the {@link TwillRunnableSpecification} that was created by {@link TwillRunnable#configure()}.
+ */
+ TwillRunnableSpecification getSpecification();
+
+ /**
+ * Returns an integer id from 0 to (instanceCount - 1).
+ */
+ int getInstanceId();
+
+ /**
+ * Returns the number of virtual cores the runnable is allowed to use.
+ */
+ int getVirtualCores();
+
+ /**
+ * Returns the amount of memory in MB the runnable is allowed to use.
+ */
+ int getMaxMemoryMB();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/TwillController.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/TwillController.java b/twill-api/src/main/java/org/apache/twill/api/TwillController.java
new file mode 100644
index 0000000..f31d3f9
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/TwillController.java
@@ -0,0 +1,61 @@
+/*
+ * 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.twill.api;
+
+import org.apache.twill.api.logging.LogHandler;
+import org.apache.twill.discovery.Discoverable;
+import com.google.common.util.concurrent.ListenableFuture;
+
+/**
+ * For controlling a running application.
+ */
+public interface TwillController extends ServiceController {
+
+ /**
+ * Adds a {@link LogHandler} for receiving application log.
+ * @param handler The handler to add.
+ */
+ void addLogHandler(LogHandler handler);
+
+ /**
+ * Discovers the set of {@link Discoverable} endpoints that provides service for the given service name.
+ * @param serviceName Name of the service to discovery.
+ * @return An {@link Iterable} that gives set of latest {@link Discoverable} every time when
+ * {@link Iterable#iterator()}} is invoked.
+ */
+ Iterable<Discoverable> discoverService(String serviceName);
+
+
+ /**
+ * Changes the number of running instances of a given runnable.
+ *
+ * @param runnable The name of the runnable.
+ * @param newCount Number of instances for the given runnable.
+ * @return A {@link ListenableFuture} that will be completed when the number running instances has been
+ * successfully changed. The future will carry the new count as the result. If there is any error
+ * while changing instances, it'll be reflected in the future.
+ */
+ ListenableFuture<Integer> changeInstances(String runnable, int newCount);
+
+ /**
+ * Get a snapshot of the resources used by the application, broken down by each runnable.
+ *
+ * @return A {@link ResourceReport} containing information about resources used by the application.
+ */
+ ResourceReport getResourceReport();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/TwillPreparer.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/TwillPreparer.java b/twill-api/src/main/java/org/apache/twill/api/TwillPreparer.java
new file mode 100644
index 0000000..b2a3ce2
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/TwillPreparer.java
@@ -0,0 +1,146 @@
+/*
+ * 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.twill.api;
+
+import org.apache.twill.api.logging.LogHandler;
+
+import java.net.URI;
+
+/**
+ * This interface exposes methods to set up the Twill runtime environment and start a Twill application.
+ */
+public interface TwillPreparer {
+
+ /**
+ * Adds a {@link LogHandler} for receiving an application log.
+ * @param handler The {@link LogHandler}.
+ * @return This {@link TwillPreparer}.
+ */
+ TwillPreparer addLogHandler(LogHandler handler);
+
+ /**
+ * Sets the user name that runs the application. Default value is get from {@code "user.name"} by calling
+ * {@link System#getProperty(String)}.
+ * @param user User name
+ * @return This {@link TwillPreparer}.
+ *
+ * @deprecated This method will be removed in future version.
+ */
+ @Deprecated
+ TwillPreparer setUser(String user);
+
+ /**
+ * Sets the list of arguments that will be passed to the application. The arguments can be retrieved
+ * from {@link TwillContext#getApplicationArguments()}.
+ *
+ * @param args Array of arguments.
+ * @return This {@link TwillPreparer}.
+ */
+ TwillPreparer withApplicationArguments(String... args);
+
+ /**
+ * Sets the list of arguments that will be passed to the application. The arguments can be retrieved
+ * from {@link TwillContext#getApplicationArguments()}.
+ *
+ * @param args Iterable of arguments.
+ * @return This {@link TwillPreparer}.
+ */
+ TwillPreparer withApplicationArguments(Iterable<String> args);
+
+ /**
+ * Sets the list of arguments that will be passed to the {@link TwillRunnable} identified by the given name.
+ * The arguments can be retrieved from {@link TwillContext#getArguments()}.
+ *
+ * @param runnableName Name of the {@link TwillRunnable}.
+ * @param args Array of arguments.
+ * @return This {@link TwillPreparer}.
+ */
+ TwillPreparer withArguments(String runnableName, String...args);
+
+ /**
+ * Sets the list of arguments that will be passed to the {@link TwillRunnable} identified by the given name.
+ * The arguments can be retrieved from {@link TwillContext#getArguments()}.
+ *
+ * @param runnableName Name of the {@link TwillRunnable}.
+ * @param args Iterable of arguments.
+ * @return This {@link TwillPreparer}.
+ */
+ TwillPreparer withArguments(String runnableName, Iterable<String> args);
+
+ /**
+ * Adds extra classes that the application is dependent on and is not traceable from the application itself.
+ * @see #withDependencies(Iterable)
+ * @return This {@link TwillPreparer}.
+ */
+ TwillPreparer withDependencies(Class<?>...classes);
+
+ /**
+ * Adds extra classes that the application is dependent on and is not traceable from the application itself.
+ * E.g. Class name used in {@link Class#forName(String)}.
+ * @param classes set of classes to add to dependency list for generating the deployment jar.
+ * @return This {@link TwillPreparer}.
+ */
+ TwillPreparer withDependencies(Iterable<Class<?>> classes);
+
+ /**
+ * Adds resources that will be available through the ClassLoader of the {@link TwillRunnable runnables}.
+ * @see #withResources(Iterable)
+ * @return This {@link TwillPreparer}.
+ */
+ TwillPreparer withResources(URI...resources);
+
+ /**
+ * Adds resources that will be available through the ClassLoader of the {@link TwillRunnable runnables}.
+ * Useful for adding extra resource files or libraries that are not traceable from the application itself.
+ * If the URI is a jar file, classes inside would be loadable by the ClassLoader. If the URI is a directory,
+ * everything underneath would be available.
+ *
+ * @param resources Set of URI to the resources.
+ * @return This {@link TwillPreparer}.
+ */
+ TwillPreparer withResources(Iterable<URI> resources);
+
+ /**
+ * Adds the set of paths to the classpath on the target machine for all runnables.
+ * @see #withClassPaths(Iterable)
+ * @return This {@link TwillPreparer}
+ */
+ TwillPreparer withClassPaths(String... classPaths);
+
+ /**
+ * Adds the set of paths to the classpath on the target machine for all runnables.
+ * Note that the paths would be just added without verification.
+ * @param classPaths Set of classpaths
+ * @return This {@link TwillPreparer}
+ */
+ TwillPreparer withClassPaths(Iterable<String> classPaths);
+
+ /**
+ * Adds security credentials for the runtime environment to gives application access to resources.
+ *
+ * @param secureStore Contains security token available for the runtime environment.
+ * @return This {@link TwillPreparer}.
+ */
+ TwillPreparer addSecureStore(SecureStore secureStore);
+
+ /**
+ * Starts the application.
+ * @return A {@link TwillController} for controlling the running application.
+ */
+ TwillController start();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/TwillRunResources.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/TwillRunResources.java b/twill-api/src/main/java/org/apache/twill/api/TwillRunResources.java
new file mode 100644
index 0000000..4c3d2e7
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/TwillRunResources.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.twill.api;
+
+/**
+ * Information about the container the {@link TwillRunnable}
+ * is running in.
+ */
+public interface TwillRunResources {
+
+ /**
+ * @return instance id of the runnable.
+ */
+ int getInstanceId();
+
+ /**
+ * @return number of cores the runnable is allowed to use. YARN must be at least v2.1.0 and
+ * it must be configured to use cgroups in order for this to be a reflection of truth.
+ */
+ int getVirtualCores();
+
+ /**
+ * @return amount of memory in MB the runnable is allowed to use.
+ */
+ int getMemoryMB();
+
+ /**
+ * @return the host the runnable is running on.
+ */
+ String getHost();
+
+ /**
+ * @return id of the container the runnable is running in.
+ */
+ String getContainerId();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/TwillRunnable.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/TwillRunnable.java b/twill-api/src/main/java/org/apache/twill/api/TwillRunnable.java
new file mode 100644
index 0000000..4350bfb
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/TwillRunnable.java
@@ -0,0 +1,57 @@
+/*
+ * 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.twill.api;
+
+/**
+ * The {@link TwillRunnable} interface should be implemented by any
+ * class whose instances are intended to be executed in a Twill cluster.
+ */
+public interface TwillRunnable extends Runnable {
+
+ /**
+ * Called at submission time. Executed on the client side.
+ * @return A {@link TwillRunnableSpecification} built by {@link TwillRunnableSpecification.Builder}.
+ */
+ TwillRunnableSpecification configure();
+
+ /**
+ * Called when the container process starts. Executed in container machine.
+ * @param context Contains information about the runtime context.
+ */
+ void initialize(TwillContext context);
+
+ /**
+ * Called when a command is received. A normal return denotes the command has been processed successfully, otherwise
+ * {@link Exception} should be thrown.
+ * @param command Contains details of the command.
+ * @throws Exception
+ */
+ void handleCommand(Command command) throws Exception;
+
+ /**
+ * Requests to stop the running service.
+ */
+ void stop();
+
+ /**
+ * Called when the {@link TwillRunnable#run()} completed. Useful for doing
+ * resource cleanup. This method would only get called if the call to {@link #initialize(TwillContext)} was
+ * successful.
+ */
+ void destroy();
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/TwillRunnableSpecification.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/TwillRunnableSpecification.java b/twill-api/src/main/java/org/apache/twill/api/TwillRunnableSpecification.java
new file mode 100644
index 0000000..bbcc5d7
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/TwillRunnableSpecification.java
@@ -0,0 +1,76 @@
+/*
+ * 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.twill.api;
+
+import org.apache.twill.internal.DefaultTwillRunnableSpecification;
+import com.google.common.collect.ImmutableMap;
+
+import java.util.Map;
+
+/**
+ * Represents a specification of a {@link TwillRunnable}.
+ */
+public interface TwillRunnableSpecification {
+
+ String getClassName();
+
+ String getName();
+
+ Map<String, String> getConfigs();
+
+ /**
+ * Builder for constructing {@link TwillRunnableSpecification}.
+ */
+ static final class Builder {
+
+ private String name;
+ private Map<String, String> args;
+
+ public static NameSetter with() {
+ return new Builder().new NameSetter();
+ }
+
+ public final class NameSetter {
+ public AfterName setName(String name) {
+ Builder.this.name = name;
+ return new AfterName();
+ }
+ }
+
+ public final class AfterName {
+ public AfterConfigs withConfigs(Map<String, String> args) {
+ Builder.this.args = args;
+ return new AfterConfigs();
+ }
+
+ public AfterConfigs noConfigs() {
+ Builder.this.args = ImmutableMap.of();
+ return new AfterConfigs();
+ }
+ }
+
+ public final class AfterConfigs {
+ public TwillRunnableSpecification build() {
+ return new DefaultTwillRunnableSpecification(null, name, args);
+ }
+ }
+
+ private Builder() {
+ }
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/TwillRunner.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/TwillRunner.java b/twill-api/src/main/java/org/apache/twill/api/TwillRunner.java
new file mode 100644
index 0000000..0393a85
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/TwillRunner.java
@@ -0,0 +1,107 @@
+/*
+ * 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.twill.api;
+
+import org.apache.twill.common.Cancellable;
+
+import java.util.concurrent.TimeUnit;
+
+/**
+ * This interface prepares execution of {@link TwillRunnable} and {@link TwillApplication}.
+ */
+public interface TwillRunner {
+
+ /**
+ * Interface to represents information of a live application.
+ */
+ interface LiveInfo {
+
+ /**
+ * Returns name of the application.
+ * @return Application name as a {@link String}.
+ */
+ String getApplicationName();
+
+ /**
+ * Returns {@link TwillController}s for all live instances of the application.
+ * @return An {@link Iterable} of {@link TwillController}.
+ */
+ Iterable<TwillController> getControllers();
+ }
+
+ /**
+ * Prepares to run the given {@link TwillRunnable} with {@link ResourceSpecification#BASIC} resource specification.
+ * @param runnable The runnable to run through Twill when {@link TwillPreparer#start()} is called.
+ * @return A {@link TwillPreparer} for setting up runtime options.
+ */
+ TwillPreparer prepare(TwillRunnable runnable);
+
+ /**
+ * Prepares to run the given {@link TwillRunnable} with the given resource specification.
+ * @param runnable The runnable to run through Twill when {@link TwillPreparer#start()} is called.
+ * @param resourceSpecification The resource specification for running the runnable.
+ * @return A {@link TwillPreparer} for setting up runtime options.
+ */
+ TwillPreparer prepare(TwillRunnable runnable, ResourceSpecification resourceSpecification);
+
+ /**
+ * Prepares to run the given {@link TwillApplication} as specified by the application.
+ * @param application The application to run through Twill when {@link TwillPreparer#start()} is called.
+ * @return A {@link TwillPreparer} for setting up runtime options.
+ */
+ TwillPreparer prepare(TwillApplication application);
+
+ /**
+ * Gets a {@link TwillController} for the given application and runId.
+ * @param applicationName Name of the application.
+ * @param runId The runId of the running application.
+ * @return A {@link TwillController} to interact with the application or null if no such runId is found.
+ */
+ TwillController lookup(String applicationName, RunId runId);
+
+ /**
+ * Gets an {@link Iterable} of {@link TwillController} for all running instances of the given application.
+ * @param applicationName Name of the application.
+ * @return A live {@link Iterable} that gives the latest {@link TwillController} set for all running
+ * instances of the application when {@link Iterable#iterator()} is invoked.
+ */
+ Iterable<TwillController> lookup(String applicationName);
+
+ /**
+ * Gets an {@link Iterable} of {@link LiveInfo}.
+ * @return A live {@link Iterable} that gives the latest information on the set of applications that
+ * have running instances when {@link Iterable#iterator()}} is invoked.
+ */
+ Iterable<LiveInfo> lookupLive();
+
+ /**
+ * Schedules a periodic update of SecureStore. The first call to the given {@link SecureStoreUpdater} will be made
+ * after {@code initialDelay}, and subsequently with the given {@code delay} between completion of one update
+ * and starting of the next. If exception is thrown on call
+ * {@link SecureStoreUpdater#update(String, RunId)}, the exception will only get logged
+ * and won't suppress the next update call.
+ *
+ * @param updater A {@link SecureStoreUpdater} for creating new SecureStore.
+ * @param initialDelay Delay before the first call to update method.
+ * @param delay Delay between completion of one update call to the next one.
+ * @param unit time unit for the initialDelay and delay.
+ * @return A {@link Cancellable} for cancelling the scheduled update.
+ */
+ Cancellable scheduleSecureStoreUpdate(final SecureStoreUpdater updater,
+ long initialDelay, long delay, TimeUnit unit);
+}
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/4a1c943c/twill-api/src/main/java/org/apache/twill/api/TwillRunnerService.java
----------------------------------------------------------------------
diff --git a/twill-api/src/main/java/org/apache/twill/api/TwillRunnerService.java b/twill-api/src/main/java/org/apache/twill/api/TwillRunnerService.java
new file mode 100644
index 0000000..76ec136
--- /dev/null
+++ b/twill-api/src/main/java/org/apache/twill/api/TwillRunnerService.java
@@ -0,0 +1,29 @@
+/*
+ * 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.twill.api;
+
+import com.google.common.util.concurrent.Service;
+
+/**
+ * A {@link TwillRunner} that extends {@link Service} to provide lifecycle management functions.
+ * The {@link #start()} method needs to be called before calling any other method of this interface.
+ * When done with this service, call {@link #stop()} to release any resources that it holds.
+ */
+public interface TwillRunnerService extends TwillRunner, Service {
+
+}