(TWILL-100) Fix examples POMs and update documentations

- Updates to examples
- Updates to BundleJarExample application and documentation.

Signed-off-by: Terence Yim <[email protected]>

Author: Matt Anderson

.gitignore

@@ -16,6 +16,11 @@ out/
 lib/
 .idea
 
+# Eclipse Files and Dir #
+.project
+.classpath
+.settings
+
 # Gradle Files & Dir #
 build/
 .stickyStorage
@@ -26,3 +31,4 @@ target/
 logs/
 zookeeper.out
 
+/bin

src/site/markdown/GettingStarted.md

@@ -123,4 +123,69 @@ You can also stop the application through the `TwillController`:
 controller.stop().get();
 ```
 
-This will shut down the application master and all the containers.
+This will shut down the application master and all the containers.
+
+### Hello World
+
+To see Twill in action, you can run the "hello world" example applications located in the twill-examples module.
+
+#### Prerequisites
+
+* Single Node or Cluster installation of Hadoop with YARN (Hadoop >= 2.2.0) set-up and running.
+* Single Node or Cluster installation of ZooKeeper set-up and running.
+* Build of Twill Library Code (minimum, build of twill-examples module)
+
+#### Running the Examples
+
+There are two example applications you can run: HelloWorld and BundledJarExample.
+
+##### HelloWorld Application
+
+The HelloWorld application creates a simple YARN application that prints a line to the log.
+
+You can run the HelloWorld application from any node of the Hadoop cluster using the below command
+(be sure to add your ZooKeeper Host and Port):
+
+```sh
+$ CP=twill-examples-yarn-0.5.0-incubating-SNAPSHOT.jar:`hadoop classpath`; java -cp $CP org.apache.twill.example.yarn.HelloWorld {zookeeper_host:port}
+```
+
+If successful, you should see logs output to the terminal with details of the running application.  Once the application
+is finished running, check the YARN logs and you should see output like the following:
+
+```
+14:49:45.944 [TwillContainerService] INFO  o.a.twill.example.yarn.HelloWorld - Hello World. My first distributed application.
+```
+
+##### BundledJarExample Application
+
+The BundledJarExample application demonstrates the Twill functionality that allows you to run any Java application
+in Twill without worrying about library version conflicts between your application and Hadoop.  The example
+calls the main class in a sample application `Echo`, which simply logs the command line argument(s) passed to it.
+The `Echo` application uses a different version of Guava from Twill and Hadoop distributions.  BundledJarExample
+looks for the dependency in a `lib` folder packaged at the root of the `Echo` jar.
+
+You can run the BundleJarExample application from any node of the Hadoop cluster using the below command
+(be sure to add your ZooKeeper Host and Port):
+
+```sh
+$ CP=twill-examples-yarn-0.5.0-incubating-SNAPSHOT.jar:`hadoop classpath`; 
+     java -cp $CP org.apache.twill.example.yarn.BundledJarExample {zookeeper_host:port} twill-examples-echo-0.5.0-incubating-SNAPSHOT.jar echo.EchoMain arg1
+```
+
+Like with the HelloWorld example, you should see logs output to the terminal.  Once the application is complete, check
+the YARN logs as before and you should see output like the following:
+
+```
+[TwillContainerService] INFO echo.EchoMain - Hello from EchoMain: 6
+err HELLO from scatch
+[TwillContainerService] INFO echo.EchoMain - Got args: [arg1]
+
+...
+
+out HELLO from scatch
+Got args: [arg1]
+
+```
+
+Congratulations!  You have run your first Twill applications.

twill-examples/echo/pom.xml

@@ -46,6 +46,12 @@ limitations under the License.
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-api</artifactId>
+            <version>1.7.7</version>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-simple</artifactId>
+            <version>1.7.7</version>
         </dependency>
     </dependencies>
 

twill-examples/yarn/pom.xml

@@ -30,24 +30,26 @@ limitations under the License.
     <name>Apache Twill examples: YARN</name>
     <description>Examples demonstrating usage of twill-yarn</description>
     <artifactId>twill-examples-yarn</artifactId>
+    
+    <properties>
+        <guava.version>13.0.1</guava.version>
+    </properties>
 
     <dependencies>
         <dependency>
             <groupId>${project.groupId}</groupId>
             <artifactId>twill-yarn</artifactId>
             <version>${project.version}</version>
-            <scope>provided</scope>
         </dependency>
         <dependency>
             <groupId>${project.groupId}</groupId>
             <artifactId>twill-ext</artifactId>
             <version>${project.version}</version>
-            <scope>provided</scope>
         </dependency>
         <dependency>
             <groupId>com.google.guava</groupId>
             <artifactId>guava</artifactId>
-            <scope>provided</scope>
+            <version>${guava.version}</version>
         </dependency>
     </dependencies>
 

twill-examples/yarn/src/main/java/org/apache/twill/example/yarn/BundledJarExample.java

@@ -79,8 +79,8 @@ public static void main(String[] args) {
     }
 
     String zkStr = args[0];
-    BundledJarRunner.Arguments arguments = BundledJarRunner.Arguments.fromArray(
-      Arrays.copyOfRange(args, 1, args.length));
+    BundledJarRunner.Arguments arguments = new BundledJarRunner.Arguments(
+            args[1], "/lib", args[2], Arrays.copyOfRange(args, 3, args.length));
 
     File jarFile = new File(arguments.getJarFileName());
     Preconditions.checkState(jarFile.exists());