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/11/21 22:54:38 UTC
[15/15] git commit: Initial import commit.
Initial import commit.
Project: http://git-wip-us.apache.org/repos/asf/incubator-twill/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-twill/commit/1925ffaf
Tree: http://git-wip-us.apache.org/repos/asf/incubator-twill/tree/1925ffaf
Diff: http://git-wip-us.apache.org/repos/asf/incubator-twill/diff/1925ffaf
Branch: refs/heads/master
Commit: 1925ffafc30e8f35d08c9666d22dba323f1fcac0
Parents:
Author: Terence Yim <te...@continuuity.com>
Authored: Wed Nov 20 17:18:51 2013 -0800
Committer: Terence Yim <te...@continuuity.com>
Committed: Thu Nov 21 13:45:28 2013 -0800
----------------------------------------------------------------------
.gitignore | 32 +
LICENSE | 203 +++++
NOTICE | 31 +
api/pom.xml | 54 ++
.../apache/twill/api/AbstractTwillRunnable.java | 75 ++
.../main/java/org/apache/twill/api/Command.java | 114 +++
.../java/org/apache/twill/api/EventHandler.java | 146 ++++
.../apache/twill/api/EventHandlerContext.java | 26 +
.../twill/api/EventHandlerSpecification.java | 30 +
.../java/org/apache/twill/api/LocalFile.java | 46 ++
.../org/apache/twill/api/ResourceReport.java | 56 ++
.../apache/twill/api/ResourceSpecification.java | 152 ++++
.../main/java/org/apache/twill/api/RunId.java | 26 +
.../apache/twill/api/RuntimeSpecification.java | 34 +
.../java/org/apache/twill/api/SecureStore.java | 26 +
.../apache/twill/api/SecureStoreUpdater.java | 33 +
.../org/apache/twill/api/ServiceAnnouncer.java | 33 +
.../org/apache/twill/api/ServiceController.java | 70 ++
.../org/apache/twill/api/TwillApplication.java | 30 +
.../java/org/apache/twill/api/TwillContext.java | 76 ++
.../org/apache/twill/api/TwillController.java | 61 ++
.../org/apache/twill/api/TwillPreparer.java | 146 ++++
.../org/apache/twill/api/TwillRunResources.java | 51 ++
.../org/apache/twill/api/TwillRunnable.java | 57 ++
.../twill/api/TwillRunnableSpecification.java | 76 ++
.../java/org/apache/twill/api/TwillRunner.java | 107 +++
.../apache/twill/api/TwillRunnerService.java | 29 +
.../apache/twill/api/TwillSpecification.java | 327 ++++++++
.../org/apache/twill/api/logging/LogEntry.java | 58 ++
.../apache/twill/api/logging/LogHandler.java | 26 +
.../twill/api/logging/PrinterLogHandler.java | 101 +++
.../apache/twill/api/logging/package-info.java | 22 +
.../java/org/apache/twill/api/package-info.java | 21 +
.../DefaultEventHandlerSpecification.java | 57 ++
.../apache/twill/internal/DefaultLocalFile.java | 76 ++
.../twill/internal/DefaultResourceReport.java | 123 +++
.../internal/DefaultResourceSpecification.java | 70 ++
.../internal/DefaultRuntimeSpecification.java | 67 ++
.../internal/DefaultTwillRunResources.java | 106 +++
.../DefaultTwillRunnableSpecification.java | 60 ++
.../internal/DefaultTwillSpecification.java | 103 +++
.../java/org/apache/twill/internal/RunIds.java | 76 ++
.../org/apache/twill/internal/package-info.java | 22 +
common/pom.xml | 51 ++
.../org/apache/twill/common/Cancellable.java | 29 +
.../twill/common/ServiceListenerAdapter.java | 50 ++
.../java/org/apache/twill/common/Services.java | 140 ++++
.../java/org/apache/twill/common/Threads.java | 52 ++
.../filesystem/ForwardingLocationFactory.java | 34 +
.../apache/twill/filesystem/LocalLocation.java | 205 +++++
.../twill/filesystem/LocalLocationFactory.java | 58 ++
.../org/apache/twill/filesystem/Location.java | 154 ++++
.../twill/filesystem/LocationFactories.java | 67 ++
.../twill/filesystem/LocationFactory.java | 46 ++
.../org/apache/twill/common/ServicesTest.java | 106 +++
.../twill/filesystem/LocalLocationTest.java | 64 ++
core/pom.xml | 89 +++
.../AbstractExecutionServiceController.java | 207 +++++
.../twill/internal/AbstractTwillController.java | 180 +++++
.../internal/AbstractZKServiceController.java | 314 ++++++++
.../twill/internal/ApplicationBundler.java | 339 ++++++++
.../org/apache/twill/internal/Arguments.java | 46 ++
.../twill/internal/BasicTwillContext.java | 131 +++
.../java/org/apache/twill/internal/Configs.java | 45 ++
.../org/apache/twill/internal/Constants.java | 64 ++
.../apache/twill/internal/ContainerInfo.java | 36 +
.../twill/internal/ContainerLiveNodeData.java | 40 +
.../apache/twill/internal/EnvContainerInfo.java | 65 ++
.../java/org/apache/twill/internal/EnvKeys.java | 59 ++
.../apache/twill/internal/ListenerExecutor.java | 134 ++++
.../twill/internal/LogOnlyEventHandler.java | 43 +
.../twill/internal/ProcessController.java | 35 +
.../apache/twill/internal/ProcessLauncher.java | 94 +++
.../internal/SingleRunnableApplication.java | 49 ++
.../internal/TwillContainerController.java | 36 +
.../twill/internal/TwillContainerLauncher.java | 181 +++++
.../org/apache/twill/internal/ZKMessages.java | 94 +++
.../twill/internal/ZKServiceDecorator.java | 482 +++++++++++
.../twill/internal/json/ArgumentsCodec.java | 95 +++
.../apache/twill/internal/json/JsonUtils.java | 66 ++
.../twill/internal/json/LocalFileCodec.java | 67 ++
.../internal/json/ResourceReportAdapter.java | 62 ++
.../internal/json/ResourceReportCodec.java | 67 ++
.../json/ResourceSpecificationCodec.java | 61 ++
.../json/RuntimeSpecificationCodec.java | 69 ++
.../internal/json/StackTraceElementCodec.java | 56 ++
.../twill/internal/json/StateNodeCodec.java | 60 ++
.../internal/json/TwillRunResourcesCodec.java | 61 ++
.../json/TwillRunnableSpecificationCodec.java | 63 ++
.../json/TwillSpecificationAdapter.java | 163 ++++
.../internal/json/TwillSpecificationCodec.java | 127 +++
.../internal/kafka/EmbeddedKafkaServer.java | 93 +++
.../AbstractCompressedMessageSetEncoder.java | 78 ++
.../kafka/client/AbstractMessageSetEncoder.java | 79 ++
.../kafka/client/BasicFetchedMessage.java | 46 ++
.../twill/internal/kafka/client/Bufferer.java | 61 ++
.../internal/kafka/client/Compression.java | 49 ++
.../internal/kafka/client/ConnectionPool.java | 125 +++
.../kafka/client/GZipMessageSetEncoder.java | 37 +
.../kafka/client/IdentityMessageSetEncoder.java | 42 +
.../internal/kafka/client/KafkaBrokerCache.java | 326 ++++++++
.../internal/kafka/client/KafkaRequest.java | 91 +++
.../kafka/client/KafkaRequestEncoder.java | 60 ++
.../kafka/client/KafkaRequestSender.java | 26 +
.../internal/kafka/client/KafkaResponse.java | 49 ++
.../kafka/client/KafkaResponseDispatcher.java | 63 ++
.../kafka/client/KafkaResponseHandler.java | 51 ++
.../internal/kafka/client/MessageFetcher.java | 243 ++++++
.../kafka/client/MessageSetEncoder.java | 31 +
.../internal/kafka/client/ResponseHandler.java | 33 +
.../kafka/client/SimpleKafkaClient.java | 304 +++++++
.../kafka/client/SnappyMessageSetEncoder.java | 38 +
.../internal/kafka/client/TopicBroker.java | 48 ++
.../internal/kafka/client/package-info.java | 21 +
.../twill/internal/logging/KafkaAppender.java | 303 +++++++
.../internal/logging/KafkaTwillRunnable.java | 122 +++
.../twill/internal/logging/LogEntryDecoder.java | 124 +++
.../apache/twill/internal/logging/Loggings.java | 46 ++
.../org/apache/twill/internal/package-info.java | 21 +
.../apache/twill/internal/state/Message.java | 54 ++
.../twill/internal/state/MessageCallback.java | 34 +
.../twill/internal/state/MessageCodec.java | 125 +++
.../apache/twill/internal/state/Messages.java | 52 ++
.../twill/internal/state/SimpleMessage.java | 89 +++
.../apache/twill/internal/state/StateNode.java | 84 ++
.../twill/internal/state/SystemMessages.java | 48 ++
.../twill/internal/utils/Dependencies.java | 323 ++++++++
.../apache/twill/internal/utils/Instances.java | 112 +++
.../apache/twill/internal/utils/Networks.java | 47 ++
.../org/apache/twill/internal/utils/Paths.java | 46 ++
.../twill/kafka/client/FetchException.java | 77 ++
.../twill/kafka/client/FetchedMessage.java | 36 +
.../apache/twill/kafka/client/KafkaClient.java | 50 ++
.../twill/kafka/client/PreparePublish.java | 34 +
.../apache/twill/kafka/client/package-info.java | 21 +
.../apache/twill/launcher/TwillLauncher.java | 236 ++++++
core/src/main/resources/kafka-0.7.2.tgz | Bin 0 -> 8811693 bytes
.../apache/twill/internal/ControllerTest.java | 211 +++++
.../twill/internal/state/MessageCodecTest.java | 78 ++
.../internal/state/ZKServiceDecoratorTest.java | 157 ++++
.../internal/utils/ApplicationBundlerTest.java | 113 +++
.../apache/twill/kafka/client/KafkaTest.java | 220 +++++
core/src/test/resources/logback-test.xml | 18 +
discovery-api/pom.xml | 39 +
.../apache/twill/discovery/Discoverable.java | 37 +
.../twill/discovery/DiscoveryService.java | 35 +
.../twill/discovery/DiscoveryServiceClient.java | 34 +
discovery-core/pom.xml | 52 ++
.../twill/discovery/DiscoverableWrapper.java | 69 ++
.../discovery/InMemoryDiscoveryService.java | 73 ++
.../twill/discovery/ZKDiscoveryService.java | 511 ++++++++++++
.../apache/twill/discovery/package-info.java | 21 +
.../discovery/InMemoryDiscoveryServiceTest.java | 67 ++
.../twill/discovery/ZKDiscoveryServiceTest.java | 253 ++++++
.../src/test/resources/logback-test.xml | 17 +
pom.xml | 556 +++++++++++++
yarn/pom.xml | 127 +++
.../internal/yarn/Hadoop20YarnAMClient.java | 213 +++++
.../internal/yarn/Hadoop20YarnAppClient.java | 197 +++++
.../yarn/Hadoop20YarnApplicationReport.java | 107 +++
.../yarn/Hadoop20YarnContainerInfo.java | 70 ++
.../yarn/Hadoop20YarnContainerStatus.java | 53 ++
.../yarn/Hadoop20YarnLaunchContext.java | 99 +++
.../yarn/Hadoop20YarnLocalResource.java | 101 +++
.../internal/yarn/Hadoop20YarnNMClient.java | 121 +++
.../twill/internal/yarn/ports/AMRMClient.java | 149 ++++
.../internal/yarn/ports/AMRMClientImpl.java | 412 ++++++++++
.../internal/yarn/ports/AllocationResponse.java | 38 +
.../yarn/ports/AllocationResponses.java | 111 +++
.../internal/yarn/Hadoop21YarnAMClient.java | 207 +++++
.../internal/yarn/Hadoop21YarnAppClient.java | 177 ++++
.../yarn/Hadoop21YarnApplicationReport.java | 107 +++
.../yarn/Hadoop21YarnContainerInfo.java | 70 ++
.../yarn/Hadoop21YarnContainerStatus.java | 53 ++
.../yarn/Hadoop21YarnLaunchContext.java | 99 +++
.../yarn/Hadoop21YarnLocalResource.java | 101 +++
.../internal/yarn/Hadoop21YarnNMClient.java | 99 +++
.../apache/twill/filesystem/HDFSLocation.java | 193 +++++
.../twill/filesystem/HDFSLocationFactory.java | 95 +++
.../apache/twill/filesystem/package-info.java | 21 +
.../twill/internal/AbstractTwillService.java | 141 ++++
.../org/apache/twill/internal/ServiceMain.java | 201 +++++
.../ApplicationMasterLiveNodeData.java | 46 ++
.../appmaster/ApplicationMasterMain.java | 85 ++
.../ApplicationMasterProcessLauncher.java | 73 ++
.../appmaster/ApplicationMasterService.java | 799 +++++++++++++++++++
.../appmaster/ApplicationSubmitter.java | 31 +
.../appmaster/BasicEventHandlerContext.java | 38 +
.../internal/appmaster/ExpectedContainers.java | 82 ++
.../appmaster/LoggerContextListenerAdapter.java | 56 ++
.../internal/appmaster/ProvisionRequest.java | 52 ++
.../appmaster/RunnableContainerRequest.java | 58 ++
.../appmaster/RunnableProcessLauncher.java | 93 +++
.../internal/appmaster/RunningContainers.java | 427 ++++++++++
.../internal/appmaster/TrackerService.java | 222 ++++++
.../twill/internal/appmaster/package-info.java | 21 +
.../internal/container/TwillContainerMain.java | 182 +++++
.../container/TwillContainerService.java | 168 ++++
.../yarn/AbstractYarnProcessLauncher.java | 220 +++++
.../yarn/VersionDetectYarnAMClientFactory.java | 55 ++
.../yarn/VersionDetectYarnAppClientFactory.java | 50 ++
.../twill/internal/yarn/YarnAMClient.java | 117 +++
.../internal/yarn/YarnAMClientFactory.java | 26 +
.../twill/internal/yarn/YarnAppClient.java | 45 ++
.../internal/yarn/YarnAppClientFactory.java | 28 +
.../internal/yarn/YarnApplicationReport.java | 126 +++
.../twill/internal/yarn/YarnContainerInfo.java | 28 +
.../internal/yarn/YarnContainerStatus.java | 34 +
.../twill/internal/yarn/YarnLaunchContext.java | 49 ++
.../twill/internal/yarn/YarnLocalResource.java | 115 +++
.../twill/internal/yarn/YarnNMClient.java | 37 +
.../apache/twill/internal/yarn/YarnUtils.java | 279 +++++++
.../twill/internal/yarn/package-info.java | 21 +
.../twill/yarn/LocationSecureStoreUpdater.java | 54 ++
.../apache/twill/yarn/ResourceReportClient.java | 63 ++
.../org/apache/twill/yarn/YarnSecureStore.java | 42 +
.../apache/twill/yarn/YarnTwillController.java | 208 +++++
.../twill/yarn/YarnTwillControllerFactory.java | 34 +
.../apache/twill/yarn/YarnTwillPreparer.java | 600 ++++++++++++++
.../twill/yarn/YarnTwillRunnerService.java | 583 ++++++++++++++
.../org/apache/twill/yarn/package-info.java | 21 +
yarn/src/main/resources/logback-template.xml | 11 +
.../java/org/apache/twill/yarn/BuggyServer.java | 41 +
.../twill/yarn/DistributeShellTestRun.java | 64 ++
.../org/apache/twill/yarn/DistributedShell.java | 70 ++
.../java/org/apache/twill/yarn/EchoServer.java | 48 ++
.../apache/twill/yarn/EchoServerTestRun.java | 138 ++++
.../twill/yarn/EnvironmentEchoServer.java | 35 +
.../twill/yarn/FailureRestartTestRun.java | 133 +++
.../org/apache/twill/yarn/LocalFileTestRun.java | 148 ++++
.../twill/yarn/ProvisionTimeoutTestRun.java | 128 +++
.../twill/yarn/ResourceReportTestRun.java | 268 +++++++
.../org/apache/twill/yarn/SocketServer.java | 133 +++
.../apache/twill/yarn/TaskCompletedTestRun.java | 93 +++
.../twill/yarn/TwillSpecificationTest.java | 87 ++
.../org/apache/twill/yarn/YarnTestSuite.java | 127 +++
yarn/src/test/resources/header.txt | 1 +
yarn/src/test/resources/logback-test.xml | 17 +
zookeeper/pom.xml | 67 ++
.../internal/zookeeper/BasicNodeChildren.java | 66 ++
.../twill/internal/zookeeper/BasicNodeData.java | 67 ++
.../zookeeper/DefaultZKClientService.java | 525 ++++++++++++
.../zookeeper/FailureRetryZKClient.java | 240 ++++++
.../internal/zookeeper/InMemoryZKServer.java | 198 +++++
.../twill/internal/zookeeper/KillZKSession.java | 69 ++
.../internal/zookeeper/NamespaceZKClient.java | 163 ++++
.../twill/internal/zookeeper/RetryUtils.java | 50 ++
.../zookeeper/RewatchOnExpireWatcher.java | 207 +++++
.../zookeeper/RewatchOnExpireZKClient.java | 95 +++
.../zookeeper/SettableOperationFuture.java | 68 ++
.../twill/internal/zookeeper/package-info.java | 22 +
.../twill/zookeeper/ForwardingZKClient.java | 116 +++
.../zookeeper/ForwardingZKClientService.java | 78 ++
.../apache/twill/zookeeper/NodeChildren.java | 38 +
.../org/apache/twill/zookeeper/NodeData.java | 39 +
.../apache/twill/zookeeper/OperationFuture.java | 33 +
.../apache/twill/zookeeper/RetryStrategies.java | 117 +++
.../apache/twill/zookeeper/RetryStrategy.java | 48 ++
.../org/apache/twill/zookeeper/ZKClient.java | 161 ++++
.../apache/twill/zookeeper/ZKClientService.java | 96 +++
.../twill/zookeeper/ZKClientServices.java | 145 ++++
.../org/apache/twill/zookeeper/ZKClients.java | 61 ++
.../apache/twill/zookeeper/ZKOperations.java | 355 ++++++++
.../apache/twill/zookeeper/package-info.java | 22 +
.../twill/zookeeper/RetryStrategyTest.java | 94 +++
.../apache/twill/zookeeper/ZKClientTest.java | 254 ++++++
.../twill/zookeeper/ZKOperationsTest.java | 63 ++
zookeeper/src/test/resources/logback-test.xml | 17 +
268 files changed, 28356 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/1925ffaf/.gitignore
----------------------------------------------------------------------
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..7aff00d
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,32 @@
+*.class
+.*.swp
+
+# Package Files #
+*.jar
+*.war
+*.ear
+
+# Intellij Files & Dir #
+*.iml
+*.ipr
+*.iws
+atlassian-ide-plugin.xml
+out/
+.DS_Store
+lib/
+.idea
+data/
+
+# Gradle Files & Dir #
+build/
+.gradle/
+.stickyStorage
+.build/
+target/
+
+# Node log
+npm-*.log
+logs/
+
+# Singlenode run files.
+data/
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/1925ffaf/LICENSE
----------------------------------------------------------------------
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..6b0b127
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,203 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed 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.
+
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/1925ffaf/NOTICE
----------------------------------------------------------------------
diff --git a/NOTICE b/NOTICE
new file mode 100644
index 0000000..df3ad5e
--- /dev/null
+++ b/NOTICE
@@ -0,0 +1,31 @@
+This product includes software developed by The Apache Software
+Foundation (http://www.apache.org/).
+
+In addition, this product includes software developed by:
+
+Guava (https://code.google.com/p/guava-libraries) is a Google Core Libraries.
+Licensed under the Apache License 2.0.
+
+Netty (http://netty.io) is a an asynchronous event-driven network application framework.
+Licensed under the Apache License 2.0.
+
+Findbugs (https://code.google.com/p/findbugs) is a defect detection tool for Java.
+Licensed under the GNU Lesser GPL
+
+Gson (https://code.google.com/p/google-gson) is a Java library for converting Java Objects into JSON.
+Licensed under the Apache License 2.0.
+
+Snappy-java (https://code.google.com/p/snappy-java) is a Java library for compression.
+Licensed under the Apache License 2.0.
+
+SLF4J (http://www.slf4j.org/) is a logging library for Java.
+Licensed under the MIT License.
+
+Logback (http://logback.qos.ch) is a logging library for Java.
+Dual licensed under EPL/LGPL. We use it under LGPL.
+
+ASM (http://asm.ow2.org) is a bytecode manipulation library for Java.
+Licensed under the BSD License.
+
+JUnit (http://www.junit.org/) included under the Common Public License v1.0. See
+the full text here: http://junit.sourceforge.net/cpl-v10.html
http://git-wip-us.apache.org/repos/asf/incubator-twill/blob/1925ffaf/api/pom.xml
----------------------------------------------------------------------
diff --git a/api/pom.xml b/api/pom.xml
new file mode 100644
index 0000000..ea731f2
--- /dev/null
+++ b/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>1.3.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/1925ffaf/api/src/main/java/org/apache/twill/api/AbstractTwillRunnable.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/AbstractTwillRunnable.java b/api/src/main/java/org/apache/twill/api/AbstractTwillRunnable.java
new file mode 100644
index 0000000..67cec0a
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/Command.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/Command.java b/api/src/main/java/org/apache/twill/api/Command.java
new file mode 100644
index 0000000..b23b3a8
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/EventHandler.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/EventHandler.java b/api/src/main/java/org/apache/twill/api/EventHandler.java
new file mode 100644
index 0000000..ede5b65
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/EventHandlerContext.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/EventHandlerContext.java b/api/src/main/java/org/apache/twill/api/EventHandlerContext.java
new file mode 100644
index 0000000..8e58af6
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/EventHandlerSpecification.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/EventHandlerSpecification.java b/api/src/main/java/org/apache/twill/api/EventHandlerSpecification.java
new file mode 100644
index 0000000..190f222
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/LocalFile.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/LocalFile.java b/api/src/main/java/org/apache/twill/api/LocalFile.java
new file mode 100644
index 0000000..df35a3b
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/ResourceReport.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/ResourceReport.java b/api/src/main/java/org/apache/twill/api/ResourceReport.java
new file mode 100644
index 0000000..0d63378
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/ResourceSpecification.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/ResourceSpecification.java b/api/src/main/java/org/apache/twill/api/ResourceSpecification.java
new file mode 100644
index 0000000..b40682f
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/RunId.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/RunId.java b/api/src/main/java/org/apache/twill/api/RunId.java
new file mode 100644
index 0000000..7f3c4fe
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/RuntimeSpecification.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/RuntimeSpecification.java b/api/src/main/java/org/apache/twill/api/RuntimeSpecification.java
new file mode 100644
index 0000000..99e11a4
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/SecureStore.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/SecureStore.java b/api/src/main/java/org/apache/twill/api/SecureStore.java
new file mode 100644
index 0000000..707a152
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/SecureStoreUpdater.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/SecureStoreUpdater.java b/api/src/main/java/org/apache/twill/api/SecureStoreUpdater.java
new file mode 100644
index 0000000..5912247
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/ServiceAnnouncer.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/ServiceAnnouncer.java b/api/src/main/java/org/apache/twill/api/ServiceAnnouncer.java
new file mode 100644
index 0000000..d8e4358
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/ServiceController.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/ServiceController.java b/api/src/main/java/org/apache/twill/api/ServiceController.java
new file mode 100644
index 0000000..0ea64f9
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/TwillApplication.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/TwillApplication.java b/api/src/main/java/org/apache/twill/api/TwillApplication.java
new file mode 100644
index 0000000..b49e7a7
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/TwillContext.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/TwillContext.java b/api/src/main/java/org/apache/twill/api/TwillContext.java
new file mode 100644
index 0000000..b4ddb6e
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/TwillController.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/TwillController.java b/api/src/main/java/org/apache/twill/api/TwillController.java
new file mode 100644
index 0000000..f31d3f9
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/TwillPreparer.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/TwillPreparer.java b/api/src/main/java/org/apache/twill/api/TwillPreparer.java
new file mode 100644
index 0000000..b2a3ce2
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/TwillRunResources.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/TwillRunResources.java b/api/src/main/java/org/apache/twill/api/TwillRunResources.java
new file mode 100644
index 0000000..4c3d2e7
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/TwillRunnable.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/TwillRunnable.java b/api/src/main/java/org/apache/twill/api/TwillRunnable.java
new file mode 100644
index 0000000..4350bfb
--- /dev/null
+++ b/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/1925ffaf/api/src/main/java/org/apache/twill/api/TwillRunnableSpecification.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/twill/api/TwillRunnableSpecification.java b/api/src/main/java/org/apache/twill/api/TwillRunnableSpecification.java
new file mode 100644
index 0000000..bbcc5d7
--- /dev/null
+++ b/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() {
+ }
+ }
+}