TiniHttpServer Home Page

This is the home page of the TiniHttpServer, a multi-threaded HTTP server for TINI that supports Java Servlets. In other words, servlets on a SIMM!!!


Table of Contents

  1. Introducing TiniHttpServer
  2. System Requirements
  3. How to Get TiniHttpServer
  4. How to Use TiniHttpServer on Your TINI
  5. Servlets Included in the Distribution
  6. How to Create Your Own Servlets for TINI
    1. Steps to perform one time only
    2. Steps to perform for each servlet you develop
  7. How to Use TiniHttpServer on Any Java System
  8. Configuring TiniHttpServer with Properties Files
    1. Properties file format
    2. Properties recognized by TiniHttpServer
    3. Properties recognized by servlets
    4. How to specify a properties file when starting TiniHttpServer
  9. The Transfer Log
  10. Limiting the Size of Log Files
  11. Limitations and Restrictions of Current Version
  12. Version History
  13. Licensing


Introducing TiniHttpServer

Return to Table of Contents

TiniHttpServer is a multi-threaded HTTP server for TINI that supports Java Servlets. TiniHttpServer turns your TINI into a web server with server-side programming capabilities. As distributed, TiniHttpServer is ready to serve up your Java applets, HTML documents, and other files directly from your TINI, plus it is bundled with five demonstration servlets. TiniHttpServer is free and, being licensed under the GNU General Public License, full source code is available. TiniHttpServer was created by Smart Software Consulting, which holds the copyright on it.


System Requirements

[Return to Table of Contents]

To use TiniHttpServer as distributed, you must have:

  1. A TINI board.
  2. TINI 1.01 firmware installed. This version of TiniHttpServer is not likely to run on other versions of the firmware.
  3. The TiniHttpServer software.

If you want to write your own servlets for TINI, you must have:

  1. All of the above, plus...
  2. Version 1.2 of the Java Development Kit.
  3. Version 2.1 of the Java Servlet Development Kit.


How to Get TiniHttpServer

Return to Table of Contents

TiniHttpServer is available from Smart Software Consulting. Simply go to the URL shown here to get the latest version:

http://www.smartsc.com/tini/TiniHttpServer/TiniHttpServer012.zip


How to Use TiniHttpServer on your TINI

Return to Table of Contents

These instructions assume you have obtained all of the required hardware and software. They also assume you are running a Windows operating system. If you are smart enough to run something else, you are smart enough to figure out what you need to do differently for your system.

  1. Extract the TiniHttpServer distribution file, TiniHttpServer012.zip. Be sure to maintain the directory structure.

  2. Open a Command Prompt Window and change to the TiniHttpServer0.12 directory that should have been created in Step 1.

  3. If you have changed/deleted the user/password of root, edit the file deploy.cmd and change the user name (on line one) from root to something appropriate and the password (on line two) from tini to something appropriate.

  4. Run the batch file deploy.bat, passing the hostname or IP address of your TINI as a command line parameter. For example, if your TINI is named kumquat, you would type:

    deploy kumquat

    After this is finishes, your TINI should have the following files:

  5. Using telnet, login to your TINI. You can use JavaKit to login to your TINI, but then you will not see the output when TiniHttpServer is run in the background.

  6. Type: source /bin/TiniHttpServer

    After a short while, you should see the following:

    SSC Web Server/0.12
    Copyright (C) 1999,2000  Smart Software Consulting
    
    iButtonServlet: init
    
  7. Point your web browser at your TINI. For example, if your TINI is named kumquat, you should go to the following URL:

    http://kumquat/

  8. If you want to serve other documents from your TINI, FTP them to the /docs directory (or below it). The file /docs/foo/bar.html can be accessed from a web browser via the following URL:

    http://kumquat/foo/bar.html


Servlets Included in the Distribution

Return to Table of Contents

The TiniHttpServer distribution includes eight servlets: SnoopServlet, SessionServlet, AuthenticatedServlet, BackupServlet, TiniServlet, iButtonServlet, FamilyCode10Servlet, and FamilyCode20Servlet.

These servlets can be accessed via the following URLs (assuming your TINI is named kumquat):


How to Create Your Own Servlets for TINI

Return to Table of Contents

These instructions assume you have obtained all of the required hardware and software. They also assume you are running a Windows operating system. If you are smart enough to run something else, you are smart enough to figure out what you need to do differently for your system.

Steps to perform one time only

  1. Install the Java Development Kit version 1.2.

  2. Install the Java Servlet Development Kit version 2.1.

  3. Extract the TiniHttpServer distribution file, TiniHttpServer012.zip. Be sure to maintain the directory structure.

  4. Open a Command Prompt Window and change to the TiniHttpServer0.12 directory that should have been created in Step 1.

  5. If you have changed/deleted the user/password of root, edit the file deploy.cmd and change the user name (on line one) from root to something appropriate and the password (on line two) from tini to something appropriate.

  6. Edit the file tinienv.bat and ensure that all the paths and files accurately reflect your installations of the various components.

  7. Change to the TiniHttpServer0.12 directory (if you are not already there).

  8. Run the batch file onetime.bat. The only message you should see is this:
    TINI build.
    Note: 2 files use or override a deprecated API.  Recompile with "-deprecation" for details.
    1 warning
    

Steps to perform for each servlet you develop

  1. Develop your servlet.

  2. Change to the TiniHttpServer0.12 directory (if you are not already there).

  3. Edit the file compile.bat and add your servlet's source code filename(s) to the line starting with set SERVLET_SRC=. You may also remove source code filenames for any unwanted servlets from this line. Source code filenames must be specified as either relative paths from the src subdirectory or absolute paths. If you do remove source code filenames, be sure to remove the corresponding class files, if any, from the classes.tini subdirectory. Note: .tini files are currently limited to 64KB. You may find that you have to remove some or all of the sample servlets in order to keep the .tini file within the 64KB limit.

  4. Run the batch file compile.bat. Unless your code causes some error or warning messages (i.e. it uses deprecated API calls), the only message you should see is this:
    TINI build.
  5. If there are any errors, go back to step 1, 2, or 3 and fix the problem.

  6. Run the batch file tiniconv.bat. This will generate many lines of output, but should complete without any error messages. The last lines of output should look like this:
    Class bytes written: #####
    Header bytes written: ##
    Applet length read: #####
    CRC Value: ########
    Signature length: #
    
  7. If there are any errors, go back to step 1, 2, or 3 and fix the problem.

  8. If TiniHttpServer is currently running on your TINI, use ps and kill to stop it.

  9. Run the batch file deploy.bat, passing the hostname or IP address of your TINI as a command line parameter. For example, if your TINI is named kumquat, you would type:

    deploy kumquat

    After this is finishes, your TINI should have the following files:

  10. Using telnet, login to your TINI. You can use JavaKit to login to your TINI, but then you will not see the output when TiniHttpServer is run in the background.

  11. Type: source /bin/TiniHttpServer

    After a short while, you should see the following:

    SSC Web Server/0.12
    Copyright (C) 1999,2000  Smart Software Consulting
    
    iButtonServlet: init
    

    If your servlet is preloaded (see Properties recognized by servlets), you will also see your servlet's initialization messages, if any.

  12. Point your web browser at your TINI. For example, if your TINI is named kumquat, you should go to the following URL:

    http://kumquat/

  13. If you want to serve other documents from your TINI, FTP them to the /docs directory (or below it). The file /docs/foo/bar.html can be accessed from a web browser via the following URL:

    http://kumquat/foo/bar.html

  14. To access your servlet (assuming your TINI is named kumquat and your servlet class is com.acme.BigMagnetServlet) go to the following URL:

    http://kumquat/servlet/com.acme.BigMagnetServlet

  15. To start TiniHttpServer every time your TINI reboots, add the following line to the end of your /etc/.startup file:

    java /bin/TiniHttpServer /etc/server.props &


How to Use TiniHttpServer on Any Java System

Return to Table of Contents

As of version 0.6, TiniHttpServer can be used on any Java system. You can now develop and debug servlets on your PC, then deploy them to your TINI once you have them working. This greatly reduces the build/debug cycle time. With Java iButton classes and javax.comm, you can develop servlets that use serial and 1-wire resources on your favorite Java platform using you favorite development tools. These servlets can then be deployed to TINI with no source code modifications. This is starting to realize the write-once-run-anywhere promise of Java. Of course, this only works if your servlets do not need any TINI specific functionality and do not use any Java functionality not available on TINI.

Note: When TiniHttpServer 0.12 was released, Dallas Semiconductor had not yet released Java iButton classes that correspond to TINI's iButton classes. As a result, you will have to omit iButtonServlet, FamilyCode10Servlet, FamilyCode20Servlet, TiniServlet, and all of the classes in the com.smartsc.ibutton package.

To use TiniHttpServer on any Java platform, follow the steps given in How to Create Your Own Servlets for TINI with the following changes:

  1. When running onetime.bat and compile.bat, provide a command line parameter that is not "tini" (e.g. use "pj" for pure java). This will cause these batch files to use the JDK and the not-yet-available Java iButton classes instead of the TINI classes. It will also produce .class files in the classes directory instead of the classes.tini directory. You should see the same messages as when building for TINI, but you will see "Pure Java build." instead of "TINI build."

  2. You do not need to run tiniconv.bat or deploy.bat until your servlet is debugged and tested.

  3. To run TiniHttpServer on a non-TINI platform, run the run.bat batch file. This will use the local_server.properties file to set the document root to be tini/docs and the servlets properties file to be tini/etc/servlets.props. You can then access TiniHttpServer from your browser by using the following URL:

    http://localhost/

    Note that TiniServlet is not supported on non-TINI platforms. You may see messages about TiniServlet not being found. This is normal.


Configuring TiniHttpServer with Properties Files

Return to Table of Contents

Various aspects of TiniHttpServer can be configured with a properties file. Servlets also have the ability to be configured with a properties file. This section describes the properties recognized by TiniHttpServer, the properties recognized by servlets, and how to specify a properties file when starting TiniHttpServer. As of version 0.6, all properties files should be in the format specified by java.util.Properties.

Properties recognized by TiniHttpServer

TiniHttpServer can be configured by setting various properties in a properties files. TiniHttpServer properties fall into three categories: server related properties, servlet related properties, and session related properties.

Server related property names

Property Name

Default Value

Purpose

server.bufferSize 512 Size, in bytes, of the input and output buffers. Other values may provide better throughput. (If you find a better value, please let us know.)
server.docRoot /docs Specifies the document root directory of TiniHttpServer. If you experience problems when using relative paths, try switching to fully qualified paths (and let us know the details of your problems).
server.indexFile index.html Specifies the name of the file to show if the requested URL specifies just a directory.
server.logFile (No default) Specifies the name of the log file to which TiniHttpServer will send all output. If not specified, TiniHttpServer will send all output to System.out.
server.mail.from (No default) Specifies the text to use in the From: header when e-mailing log files.
server.mail.to (No default) E-mail address to which log files will be e-mailed when they reach the size specified by server.maxLogSize.
server.maxLogSize (No default) Specifies the maximum size that the server log or transfer log can attain before it is mailed to the server.mail.to address.
server.maxHandlers 5 Specifies the maximum number of concurrently handled requests.
server.mimeTypesFile (No default) Specifies the name of a properties file containing additional extension to MIME-type mappings. The lines should be formatted ".ext=mime/type"
server.port 80 Specifies the TCP/IP port on which TiniHttpServer listens for requests.
server.requestTimeout 10 Specifies the number of seconds TiniHttpServer will wait for a request on a particular connection. If a browser connects to TiniHttpServer, but does not send a request within this time frame, TiniHttpServer will respond with 408 Request-timeout.
server.stackTrace false Specifies whether to print a stack trace when logging exceptions. Set to "true" to enable.
server.transferLog (Server log) Specifies the file to which transfer log entries are sent. If omitted, the entries are sent to the server log. Set to "-" to force transfer log entries to System.out.
server.verbose false Specifies whether to display properties on startup. Set to "true" to enable. This property can also be enabled by specifying "-v" on the command line.

Servlet related property names

Property Name

Default Value

Purpose

servlet.prefix /servlet/ Specifies the URL prefix which signifies that this request is intended for a servlet.
servlet.propFile /etc/servlets.props Specifies the name of the servlet properties file.

Session related property names

Property Name

Default Value

Purpose

session.name sscSessionId Specifies the name used for the automatic session tracking cookie or URL parameter (depending on which session type is configured).
session.timeout 3600 Specifies the initial number of seconds that are allowed between requests for a particular session. Sessions that exceed this time between requests will be invalidated and discarded.
session.type Cookie Specifies the technique used for automatic session tracking. Set to "Cookie" to use cookies, "URL" to use URL rewriting, or "None" to disable automatic session tracking.

Properties recognized by servlets

Servlets can be configured by a servlet properties file. This file defaults to /etc/servlets.props, but can be changed in TiniHttpServer's optional properties file.

Property Name

Purpose

<alias>.code Creates an alias for the servlet class specified by the property value. If your servlet class is com.acme.BigMagnetServlet, then adding the line

magnet.code=com.acme.BigMagnetServlet

to your servlet properties file will allow users to access your servlet as http://kumquat/servlet/magnet instead of http://kumquat/servlet/com.acme.BigMagnetServlet (assuming your TINI is named kumquat).
<servlet.class.name>.initArgs Specifies initial arguments for a servlet. The property value contains the initial arguments as name=value pairs separated by semicolons.
<servlet.class.name>.preload If set to "true", the servlet will be pre-loaded when TiniHttpServer starts. If set to "false", the servlet will not be loaded until the first request for it is received.

How to specify a properties file when starting TiniHttpServer

The TiniHttpServer properties file can be specified by passing the name of the property file on the command line. For example, to use the sample properties file named /etc/server.props, you could start TiniHttpServer like this:

java TiniHttpServer.tini /etc/server.props

Inserting "-v" as the first parameter will cause TiniHttpServer to display its properties (assuming its output is directed to System.out). This is true even if you do not specify a properties file.

You can also start TiniHttpServer using the sample properties file by "sourcing" the sample startup script like this:

source /bin/TiniHttpServer

Note that there is no .tini extension on the startup script file name. The sample startup script starts TiniHttpServer in the background using /etc/server.props as the properties file.


The Transfer Log

Return to Table of Contents

As of version 0.7, TiniHttpServer logs every completed (but not necessarily successful) request to the Transfer Log. Each line of the transfer log has the following format:

remote.IP.address - authorized_user [date] "request" status_code content_length "referrer" "user_agent"

remote.IP.address This is the IP address from which the request was received.
authorized_user If the request included authorization information, the user name; otherwise "-"
date This is the date and time of the request.
request The is the first line of the HTTP request, which includes the HTTP method, the URI, and the HTTP version used.
status_code This is the status code that was sent back to the requester.
content_length This is the length of the content that was sent back to the requester, if known; otherwise "-"
referrer The Referer header, if any, from the HTTP request.
user_agent The User-Agent header, if any, from the HTTP request.

Some sample lines from a transfer log are shown here...

10.0.0.1 - - [Sat Jun 3 20:44:16 PST 2000] "GET / HTTP/1.0" 200 1016 "" "Mozilla/4.0 (compatible; MSIE 5.0; Windows NT; DigExt)"
10.0.0.1 - - [Sat Jun 3 20:46:23 PST 2000] "GET /servlet/iButtonServlet HTTP/1.0" 200 - "http://kumquat/" "Mozilla/4.0 (compatible; MSIE 5.0; Windows NT; DigExt)"
10.0.0.1 - - [Sat Jun 3 20:49:08 PST 2000] "GET /servlet/iButtonServlet?adapter=TINISerialAdapter&port=TINI_1_Wire HTTP/1.0" 200 - "http://kumquat/servlet/iButtonServlet" "Mozilla/4.0 (compatible; MSIE 5.0; Windows NT; DigExt)"
10.0.0.1 - - [Sat Jun 3 20:53:55 PST 2000] "GET /servlet/FamilyCode10Servlet?adapter=TINISerialAdapter&port=TINI_1_Wire&iButton=9200000014D2B710 HTTP/1.0" 200 - "http://kumquat/servlet/iButtonServlet?adapter=TINISerialAdapter&port=TINI_1_Wire" "Mozilla/4.0 (compatible; MSIE 5.0; Windows NT; DigExt)"

Transfer Log Location

By default, TiniHttpServer sends the transfer log entries to the place specified by the server.logFile property (which defaults to System.out). To send the transfer log entries to a different place, specify a filename for the server.trasferLog property. The sample server.props file specifies /logs/transfer.log as the transfer log file. To send the transfer log entries to System.out, even if the server log is sent to a file, set server.transferLog to "-".


Limiting the Size of Log Files

As time goes on, the server log and transfer log files can get rather large and consume precious memory space on TINI. To alleviate this problem, TiniHttpServer can email a log file to a specified address when it reaches a specified size and then truncate the log file. To enable this functionality, you need to edit the /etc/server.props file. The following three server properties need to be specified:

  1. server.mail.to must be set to the email address to which the logs files will be mailed.

  2. server.mail.from should be set to a meaningful and descriptive return address. Note that since your TINI probably lacks an SMTP server, you might want to set this address to your own. If you do not set this property, the SMTP mailhost (established with the Slush ipconfig -h xx.xx.xx.xx command) may provide a default value that may not be suitable.

  3. server.maxLogSize must be set to the maximum allowable log file size. When a log file meets or exceeds this size, it will be e-mailed to the address specified by server.mail.to.

You must also use the Slush ipconfig -h xx.xx.xx.xx command to setup the SMTP host through which email is sent.


Limitations and Restrictions of Current Version

Return to Table of Contents

  1. TiniHttpServer does not support Java Server Pages (JSP).

There are probably other limitations and restrictions that will cause problems, if you come across any that are not mentioned here, please send e-mail to TiniHttpServerBugs@smartsc.com.


Version History

Return to Table of Contents

Version

Comments

0.2

» Initial release.

0.3

» Improved output buffering (and added server.bufferSize property). Much better performance!

0.4

» Release supporting TINI Firmware Beta 1. Even better performance!

0.5

» Added TmexServlet.
» Enhanced Security. TINI Beta 1 added support for .. to get to the parent directory. This allowed people to access files anywhere on TINI by using URLs such as http://kumquat/../etc/.startup. Version 0.5 now responds with 403 Forbidden to any requests for files that are not in or under docRoot.

0.6

» Release supporting TINI Firmware Beta 2. Performance is still improving!
» Fixed bug in temperature calculation in TiniServlet (only affected temperatures below 0° C).
» GenericServlet.getServletName() has been removed.
» TmexServlet improved.
» FamilyCode10Servlet added.
» Made logging slightly more consistent.
» Improved HttpServletResponse.sendRedirect().
» Added server property (server.stackTrace) to enable stack traces when logging exceptions.
» TiniHttpServer now runs on any Java system!!!

0.7

» Improved TmexServlet to explicitly target all family codes and search for all iButtons.
» Added support for transfer log (and the server.transferLog property).
» Improved multi-threading so a "blank request" will not hang entire server.
» Added socket timeout (and server.requestTimeout property) so that "blank requests" will timeout.
» Simplified tracking of active handler count.
» Added support for the transfer log daemon (and the server.transferDaemon property).
» Added the transfer log daemon.
» Added miscellaneous helper files.

0.8

» Release supporting TINI Firmware Beta 2.1.
» Removed some workarounds; no new features.

0.9

» Release supporting TINI Firmware Beta 2.2.
» Improved garbage collection.
» Added abstract class com.smartsc.http.AuthenticatedHttpServlet and sample servlet AuthenticatedServlet.
» Added FamilyCode20Servlet.

0.10

» Fixed the reading of POSTed data.
» Fixed com.smartsc.http.HttpRequest.getServerName().
» Fixed com.smartsc.http.HttpRequest.getServerPort().
» Added server.mimeTypesFile server property (and /etc/mime.props file).
» Changed TiniServlet's conversion time for family code 10 devices from 500ms to 750ms to accomodate DS18S20 devices.
» Removed transfer log daemon support.
» Added support for mailing "oversized" log files.
» Fixed a bug in com.smartsc.http.HttpRequest.httpDecode() when encoded string started with a '%xx' sequence.
» Added Referer and User-Agent request headers to transfer log.
» Added favicon.ico.
» Added BackupServlet.
» Added ConvertTransferLog.java - An undocumented program to convert TiniHttpServer's transfer log files into a format that can be recognized by transfer log analyzers. This just converts the date and time field from a numeric format to a more conventional format.

0.11

» Version supporting TINI 1.0.
» Renamed TmexServlet to iButtonServlet.
» Fixed bug in HttpRequest.getContentType().
» Ignore query strings when GETting documents.
» GETting documents now uses BufferedInputStream.
» ServletInputStream now uses BufferedInputStream as its underlying InputStream.
» ServletInputStream.readLine() handles CR characters better.
» HttpRequest.httpDecode() now correctly decodes '+' to a space character.
» Added support for date related HTTP headers.
» Added logic for If-Modified-Since header when GETting documents.
» Added support for HEAD method.
» Changed date format in the transfer log to a human-readable format.
» Removed ConvertTransferLog.java

0.12

» Version supporting TINI OS 1.01.
» Fixed bug in HttpResponse that was not flushing/closing ServletOutputStream when done.
» Modified all iButton code to use the new iButton API.
» Modified iButtonContainer20 to increase performance. It now uses select() instead of isPresent().


Licensing

Return to Table of Contents

Smart Software Consulting holds the copyright to TiniHttpServer, which is licensed under the GNU General Public License, version 2, as published by the Free Software Foundation.


Copyright © 1999,2000 Smart Software Consulting