Getting Started Tutorial with Tynamo(TM)-TINI

Getting Started Tutorial

This document is a short but effective tutorial on how to write your own servlets for the Tynamo™-TINI server. 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 are two tools, besides the JDK and TINI SDK, that the build process uses. These are Ant and TiniAnt. As of this writing, the latest versions of these tools are Ant 1.6.5 and TiniAnt 1.2.0. 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 TiniAnt.jar and commons-net.jar (it may be named commons-net-1.4.1.jar or something similar) libraries need to be placed into Ant's lib/ subdirectory.

One additional point is that the Tynamo™ distribution, by default, includes some example configuration files. These can be safely modified to conform to this tutorial.

[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-tini-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 tini.path property to point to the root of your TINI SDK installation. For example:

tini.path=/Java/tini1.17

Note: if you use backslashes (\) as the file separator, then you must use them in pairs (eg. tini.path=C:\\Java\\tini1.17). 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-tini-1.0.4/src
(This assumes that the Tynamo™ installation resides at /tynamo-tini-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, if you are using TINI firmware 1.10 or later, then add your full servlet classnames to reflect.classes. Again, for the example above:

reflect.classes=OneWireListServlet

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 the TINI executable 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 to build the .tini file.

[Top]

5. Update the Servlet Configuration

Open the servlets.props file in the tini/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 and MIME Types documents.

Note that some of the configuration properties refer to http-root and logs directories. When transferring files to your TINI, create these directories also.

[Top]

7. Transfer to Your TINI

Simply use an FTP client to transfer the entire contents of the tini/ subdirectory to your TINI.

There is a convenience script in tini/bin/, called WebServer, that can be used to invoke the web server on the TINI itself. Other than modifying the absolute paths in this file, all other files should remain as they are. (With the exception of any example binaries, which can be deleted.)

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 TINI. It is assumed that the FTP command was invoked from the root of your distribution.

ftp tini_address
root                Log in as 'root'
tini                Password is 'tini'
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 tini/bin        Change to the 'tini/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 TINI, navigate to the location of the files transferred in the previous step, and run the .tini file. You can do this in one of two ways: by calling the WebServer script with the command source WebServer, or by running the .tini binary directly.

[Top]

9. Enjoy Your Servlets!

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

http://{TINI 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 TINI

Example Command-Line FTP Session

8. Invoke the Web Server

9. Enjoy Your Servlets!

More `src.files` Examples