The following sections will walk you through creating your first Java project injected with Appcelerator Entourage. We will also build a simple sample application to help get you going with Appcelerator Entourage.
Before you begin know that we assume you have at least the Java SE Development Kit, Apache Ant and a servlet container installed on your machine. Popular choices for servlet container include Apache Tomcat and Jetty. Please visit their respective sites for information on how to install them.
Once Java and your servlet container are ready you will need to download the Appcelerator Entourage package for Java. Remember where you put this. We are going to unpack it next.
We want a simple Java project that includes Appcelerator Entourage. We could use an existing project, but for simplicity we are going to create a new one. Most of what we want was included in our download of Appcelerator Entourage, but we need a couple more things.
First we need a project directory. Run the following command:
mkdir -p path/to/your/new/application
We want the contents of our Appcelerator Entourage in a directory under our new application directory named web. So run the following command.
mkdir path/to/your/new/application/web
Then we need to unzip the Appcelerator Entourage package for Java into our new project. The process for this is different if you are on Window or *nix.
Run the following command:
unzip -q -d path/to/your/new/application/web path/to/entourage-package.zip
Unpack the archive in Windows Explorer. Select it's entire contents and copy them to the clipboard. Then paste them into your new application's web directory.
Now we are going to use Ant build and package our application. So let's drop the following Ant script into our application directory. Create a new file named build.xml in your application directory and cut and paste the following script.
<project name="MyProject" default="war" basedir="."> <property name="web" location="web"/> <property name="src" location="${web}/WEB-INF/classes"/> <property name="build" location="${web}/WEB-INF/classes"/> <property name="lib" location="${web}/WEB-INF/lib"/> <property name="dist" location="stage"/> <path id="classpath"> <fileset dir="${lib}" includes="**/*.jar"/> </path> <target name="compile" description="compile services"> <javac srcdir="${src}" destdir="${build}" classpathref="classpath"/> </target> <target name="war" depends="compile" description="make our war"> <mkdir dir="${dist}/lib"/> <jar jarfile="MyProject.war" basedir="${web}"/> </target> <target name="clean" description="clean up"> <delete file="MyProject.war"/> </target> </project>
Let's confirm that everything is working correctly. Run the following commands:
cd path/to/your/new/application ant
Drop the MyProject.war into your servlet container's webapp directory and fire her up. Then go to http://localhost:8080/myproject/servicetester.html (or whatever is appropriate for your container) and try to execute the example echo service that was included.
Let’s start by creating a simple user interface that will test remote messaging. Lets create ./web/hello_world.html and replace the body contents with the following:
<html> <head> <title>Appcelerator Entourage™ Hello World</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <script src="/javascripts/entourage.js" type="text/javascript"></script> </head> <body style="visibility:hidden" on="l:app.compiled then visible"> <!-- generate request --> <textarea id="your_message" fieldset="hello_world">type something</textarea> <div> <input type="button" value="click me" fieldset="hello_world" on="click then r:hello.world.request"/> </div> <!-- display response --> <div> You typed: <span on="r:hello.world.response then value[message]" style="color:blue"> nothing yet </span> </div> <!-- mock service --> <script type="text/javascript"> $MQL("r:hello.world.request", function(message) { $MQ({ name: "r:hello.world.response", payload: { message: message.payload.your_message } }); }); </script> </body> </html>
Run the ant script again and update your servlet container's webapp directory.
Test out your new application by accessing it at the following url: http://localhost:8080/myproject/hello_world.html (or whatever is appropriate for your container)
There are several basic concepts covered in this example. First, we use the fieldset attribute to link the TEXTAREA with the INPUT button. When a click event is generated by an element with a fieldset, Appcelerator will look for other input elements with the same fieldset value, and it will include their values in the message generated by the click event. This feature is very useful when creating forms.
Second, we show how an element can subscribe to a message and set its value based on an attribute in the message payload - in this case the message attribute.
Finally, we show an example of how to create a mock service. A mock service is a SCRIPT widget that subscribes to a remote request and responds with a remote response. This is a powerful capability because it enables you to create fully functional user interfaces (UI) without writing a single line of service code. These UIs are also 100% reusable. Once you finish your UI, you can remove your mock services as you create the remote service implementations. We call this Interactive Use Case development. You can learn more about Interactive Use Cases in the Best Practices section of this documentation.
Now we’re ready to implement the service for our Hello World example. First, remove (or comment out) the mock service that you created above. Next, open ./web/WEB-INF/classes/org/appcelerator/test/EchoService.java and create a new service method like the one below:
@Service(request = "hello.world.request", response = "hello.world.response") protected void helloWorld (Message request, Message response) throws Exception { response.getData().put("message", request.getData().getString("your_message")); }
Run the ant script again and update your servlet container's webapp directory.
Again, you should be able to test out your new application by accessing it at the following url: http://localhost:8080/myproject/hello_world.html (or whatever is appropriate for your container)