Getting Started Tutorial with Tynamo(TM)-SNAP

Getting Started Tutorial

This document is a short but effective tutorial on how to write your own servlets for Tynamo™-SNAP. Below are steps that describe the entire process, from downloading the tools, to accessing your servlet or servlets from an HTTP client. More details can be found in the Building a Web Server document.

0. Pre-Setup

Before beginning this sequence of steps, it is important to have all the necessary tools and utilities installed. Thus, this step "0" is here to provide instruction on this initial setup, if needed.

There is one tool, besides the JDK and device SDK, that the build process uses. This is the Ant utility from The Jakarta Project. As of this writing, the latest version of this tool is Ant 1.6.5. Ant also requires the Jakarta Commons/Net library for deployment using FTP.

Briefly, Ant needs the ANT_HOME and JAVA_HOME environment variables set correctly, and the bin subdirectory of the Ant installation added to the path. As well, the commons-net.jar (it may be named commons-net-1.4.1.jar or something similar) library needs to be placed into Ant's lib/ subdirectory.

[Top]

1. Download Tynamo™

Download the latest version of Tynamo™ from tynamo.qindesign.com. (This is the current homepage.) The easiest way to install the package is to create a directory, such as tynamo-snap-1.0.4, and unzip the file into this location.

[Top]

2. Write Servlets

This step demonstrates how to write a simple servlet. There is much literature on this subject, for example in the Documentation section of the Servlets home page, so a relatively small example is presented here. Please remember, however, that the Tynamo™ server complies with the Servlet 2.2 specification, and not 2.3 or above.

import com.dalsemi.onewire.*;
import com.dalsemi.onewire.adapter.DSPortAdapter;
import com.dalsemi.onewire.container.OneWireContainer;

import java.io.IOException;
import java.util.Enumeration;
import javax.servlet.ServletOutputStream;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
 * Simple servlet that lists all 1-Wire devices found on all adapters.
 *
 * @author Shawn Silverman
 */
public class OneWireListServlet extends HttpServlet {
    /**
     * Process a GET request.
     */
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
        throws ServletException, IOException
    {
        resp.setContentType("text/html");
        ServletOutputStream out = resp.getOutputStream();
        out.print("<html><head><title>1-Wire List Servlet</title></head><body>");
        out.print("<h1>1-Wire List</h1>");
        out.print("<p>This servlet lists all 1-Wire devices on all the adapters.</p>");

        // Iterate through the adapters

        Enumeration adapters = OneWireAccessProvider.enumerateAllAdapters();
        while (adapters.hasMoreElements()) {
            DSPortAdapter a = (DSPortAdapter)adapters.nextElement();
            out.print("<h2>Adapter: ");
            out.print(a.getAdapterName());
            out.print("</h2>");

            // Print all 1-Wire containers on this adapter

            try {
                OneWireContainer c = a.getFirstDeviceContainer();
                if (c != null) {
                    out.print("<p>1-Wire devices found:</p><ul>");
                    do {
                        out.print("<li>");
                        out.print(c.getAddressAsString());
                        out.write(' ');
                        out.print(c.getName());
                        out.print("</li>");

                        c = a.getNextDeviceContainer();
                    } while (c != null);
                    out.print("</ul>");
                } else {
                    out.print("No 1-Wire devices found.");
                }
            } catch (OneWireException ex) {
                out.print("<strong>Error while accessing adapter: ");
                out.print(ex.toString());
                out.print("</strong>");
            }
        }

        out.print("</body></html>");
    }
}

Save this code as OneWireListServlet.java in a directory named src underneath the Tynamo™ installation.

[Top]

3. Update the Build Configuration

Open the build.properties file in the root of your Tynamo™ installation. The first thing you need to do is change the snap.path property to point to the root of your SNAP SDK installation. For example:

snap.path=/Java/snap1.0.6

Note: if you use backslashes (\) as the file separator, then you must use them in pairs (eg. tini.path=C:\\Java\\snap1.0.6). This applies to all of the build properties.

Next, change src.paths to point to the root of your servlet source code. For example, if you have a directory named src underneath /projects/myapp, then change src.paths to read:

src.paths=/projects/myapp/src

Personally, I like to place a src/ directory underneath the root of the Tynamo™ installation. If you have done this, then src.paths should read something like:

src.paths=/tynamo-snap-1.0.4/src
(This assumes that the Tynamo™ installation resides at /tynamo-snap-1.0.4.)

Note also that the path can be relative if you choose.

After this, add an Ant-style list of source files to the src.files property. For the example above, this would read:

src.files=OneWireListServlet.java

Finally, choose the name of the JAR file that will hold our servlet class:

target.jar=myclasses.jar

Our servlet does not depend on any additional classes, so leave the dependency.classpath property blank.

More `src.files` Examples

If, say, you have more than one source file in the package com.entity.myapp, then src.files would read as:

src.files=com/entity/myapp/*.java

You can even include more than one subpackage by doing this:

src.files=com/entity/myapp/**/*.java

Please consult the Ant documentation for more details about specifying files.

[Top]

4. Build Using Ant

Build your servlets using Ant. In many cases, all you need to do is execute the ant command from the command line, in the same place as your Tynamo™ installation. Ant will automatically look for the included build.xml file, use your new build configuration, and then proceed with the build.

[Top]

5. Update the Servlet Configuration

Open the servlets.props file in the snap/bin/ directory of your Tynamo™ installation. You must provide a mapping, a classname, and any initialization arguments for each servlet. Further details can be found in the Servlet Configuration Properties document. For our 1-Wire example, one possibility for these settings is:

OneWireList.mapping=/servlet/OneWireList
OneWireList.class=OneWireListServlet

We have just indicated to the web server that any request for the path /servlet/OneWireList will access our example servlet. Also, it is worthwhile to note that this class does not exist inside of a package, so the full classname is just the classname itself: OneWireListServlet as oppsed to com.widgets.OneWireListServlet.

It is also worth mentioning that smaller servlets.props files take less time to load. Removing unnecessary lines will cause the server to start faster.

[Top]

6. Additional Configuration

For additional web server configuration, you are referred to the Server Configuration Properties and MIME Types documents.

We also need to tell the SNAP's virtual machine where to find our new servlet class. We do this by prepending /web/bin/myclasses.jar to the classpath in the WebServer script. The file should now look something like (note that the line may be wrapped, but should be on one line):

java -classpath /web/bin/myclasses.jar:/web/bin/tws_core.jar:/web/examples/servlet_examples.jar -r com.qindesign.snap.http.Main /web/bin/webserver.props &

To use the log (or general) mailing feature, the mailhost address must be set using either the ipconfig command, the SNAP API, or the mail.host system property. For the current release (1.0.6), this step can be facilitated by inserting something similar to this line into the WebServer script:

setenv mail.host my.mail.host.com

where my.mail.host.com is the address of your mail server.

[Top]

7. Transfer to Your SNAP

Simply use an FTP client to transfer the entire contents of the snap/ subdirectory to your SNAP.

There is a convenience script in snap/bin/, called WebServer, that can be used to invoke the web server on the SNAP itself. Other than modifying the absolute paths in this file, all other files should remain as they are.

To include support for the provided example servlets, also transfer the examples/servlet_examples.jar file. Update the classpath in the WebServer script as needed.

It is recommended to have some sort of dedicated user, 'web' for example, in whose account all the files are stored. Inside this user's home directory, create these subdirectories:

bin for the the above-mentioned binaries and configurations,
http-root for any static content such as HTML files, and
logs to store the transfer logs and any server messages.

Alternatively, the server can be deployed using Ant.

Example Command-Line FTP Session

What follows is a sample FTP session that transfers the server to your SNAP. It is assumed that the FTP command was invoked from the root of your distribution.

ftp snap_address
root                Log in as 'root'
snap                Password is 'snap'
bin                 Change the transfer mode to binary
mkdir web           Create a root location for the webserver
cd web
mkdir bin           Create directories necessary for the webserver
mkdir http-root
mkdir logs
cd bin              Change to the 'bin' directory
lcd snap/bin        Change to the 'snap/bin' directory on the local machine
prompt off          Suppress prompting for each file
mput *              Transfer all files in this directory
cd ../http-root     Transfer all web pages and images
lcd ../http-root
mput *
quit                End the session

[Top]

8. Invoke the Web Server

Log on to your SNAP, navigate to the location of the files transferred in the previous step, and run the WebServer script with the command source WebServer.

[Top]

9. Enjoy Your Servlets!

Use a web browser or some other HTTP client and connect to your SNAP web server:

http://{SNAP address}/servlet/OneWireList

Enjoy!!

[Top]

Table of Steps

0. Pre-Setup

1. Download Tynamo™

2. Write Servlets

3. Update the Build Configuration

More src.files Examples

4. Build Using Ant

5. Update the Servlet Configuration

6. Additional Configuration

7. Transfer to Your SNAP

Example Command-Line FTP Session

8. Invoke the Web Server

9. Enjoy Your Servlets!

More `src.files` Examples