Provided Example Servlets

There are a number of example servlets, with source code, provided with this distribution. This document explains and discusses how to use each one.

Please note that not all the example servlets will be built into your binary if you include the ExampleServlets dependency group (see Including Your Own Classes and dependency.groups) in your build.properties file. Consult the examples/servlet_examples_dep.txt file in the distribution for the correct dependency group.

  1. SendMail
  2. Shutdown
  3. AuthExample
  4. OneWireServlet
  5. RequestInfo
  6. TiniInfo
  7. FastOneWireServlet
  8. SimpleOneWireServlet
  9. LogViewer
  10. ServerPush
  11. TemplateDemo
  12. ToggleLED
com.qindesign.servlet.SendMailServlet

Sends mail to a single address specified by the init. parameter, mailTo. Mail is sent via a POST request and there are four parameters. They are:

  1. from – the sender's address.
  2. subject – the subject line.
  3. content – the message content.
  4. nextPath – location to forward the request once the mail is sent.

All four parameters are optional, however, not including any of the information is probably of limited value.

It is required that both the mailTo initialization parameter and the mailhost be set, or else this will throw a ServletException. The parameter is set in the servlet.props file like this:

SendMail.initParams=mailTo=some@mail.address

Included in the distribution are two files that make use of this servlet: feedback.html and feedback-sent.html. These are found in the sample http-root/ directory. The first is a form that allows a user to fill out an email. Once this is sent, they are forwarded to the second document.

To add this servlet to the build, add "SendMailServlet" to the dependency.groups and "com.qindesign.servlet.example.SendMailServlet" to the reflect.classes build properties. Also be sure to add something suitable to the Servlet Configuration file.

[Top]

com.qindesign.servlet.ShutdownServlet

Capable of shutting down the server. This makes use of authentication to authorize a shutdown. An initialization parameter named auth stores the username and password. The format is: auth=user:pass.

This servlet is only capable of shutting down the server if two conditions are satisfied. First, the server.shutdownEnabled server property must be set to true, and second, the server.shutdownPasswordFile server property must be set to a valid file. If the user passes the authentication, then a link to a special shutdown URL will be provided.

To add this servlet to the build, add "ShutdownServlet" to the dependency.groups and "com.qindesign.servlet.example.ShutdownServlet" to the reflect.classes build properties. Also be sure to add something suitable to the Servlet Configuration file.

[Top]

com.qindesign.servlet.example.AuthExampleServlet
Demonstrates the use of authentication in a servlet. The username & password are "test" & "test", and the realm is "Realm".

When using this servlet, be sure and set the include.authentication build property to true.

This servlet is, by default, included in the "ExampleServlets" dependency group.

[Top]

com.qindesign.servlet.example.OneWireServlet

Allows exploration of the 1-Wire network attached to the TINI. This servlet allows you to drill down from the adapters, through the devices, and into the internal memory of each device.

This servlet can be configured to provide alternative information for each family code by specifying an "include" servlet in the list of initialization parameters. For example, here is a possible snippet for a servlets.props file:

[Very important NOTE: JDK 1.1, and therefore TINI, does not support continuation lines with the '\' character. Thus, make sure you put the initParams on one line. The use of this in the following example is just for illustration.]

#
# Useful servlet that can explore all aspects of a 1-Wire system
#
OneWireServlet.mapping=/servlet/OneWireServlet
OneWireServlet.class=com.qindesign.servlet.example.OneWireServlet
OneWireServlet.initParams=familyCode10=TemperatureInclude,\
                          familyCode21=TemperatureInclude,\
                          familyCode05=SwitchInclude,\
                          familyCode12=SwitchInclude,\
                          familyCode1f=SwitchInclude
#
# Family code includes for use by OneWireServlet
#
TemperatureInclude.mapping=
TemperatureInclude.class=com.qindesign.servlet.example.TemperatureInclude
SwitchInclude.mapping=
SwitchInclude.class=com.qindesign.servlet.example.SwitchInclude

Note the use of two additional servlets, one for temperature and one for switches. You can write your own family code servlets simply by adding yours to the initialization parameters of this servlet. Specify familyCodeXX=<servlet name>.

There are two request attributes that will be passed to these servlets. These are container and queryString. The container attribute will contain an instance of the specific container class appropriate for the family code, and queryString will contain the exact query string necessary to append to the request for access to the included servlet.

In addition, there is a base OneWireSensorInclude class that provides checking for a valid request, and also prints a small header summarizing the name and address of the device. The TemperatureInclude and SwitchInclude servlets extend this class.

Please consult the source code for additional examples and information.

[Top]

com.qindesign.servlet.example.RequestInfoServlet
Displays details about your HTTP request. This includes information about the Request-Line, and a list of all the request headers and parameters.

This servlet is, by default, included in the "ExampleServlets" dependency group.

[Top]

com.qindesign.servlet.example.TiniInfoServlet
Displays detailed information about the TINI on which the server is running. The server uptime is also shown.

This servlet is, by default, included in the "ExampleServlets" dependency group.

[Top]

com.qindesign.servlet.example.FastOneWireServlet

Explores the 1-Wire network connected to the TINI. The output is XML. This means it is more easily machine-parsable than the output from OneWireServlet. It also means it is a little bit faster.

The servlet is flexible in that it allows you to list adapters and devices. Please consult the source code and Javadocs for a description of the request format and XML output.

To add this example to your server, add "FastOneWireServlet" to the dependency.groups property in the build.properties file. Also add the appropriate classname to reflect.classes.

[Top]

com.qindesign.servlet.example.SimpleOneWireServlet
Shows information from one 1-Wire device. The output is plain text. Please consult the source code and Javadocs for a description of the request format and output.

To add this example to your server, add "SimpleOneWireServlet" to the dependency.groups property in the build.properties file. Also add the appropriate classname to reflect.classes.

[Top]

com.qindesign.servlet.example.LogViewerServlet
Shows the current contents of the server and transfer logs. This demonstrates how to use the server configuration properties stored in the context attributes.

This servlet is, by default, included in the "ExampleServlets" dependency group.

[Top]

com.qindesign.servlet.example.ServerPushServlet
Demonstrates how to send data using a "server push" technique. It is known to work with the Netscape, Opera, and Safari browsers, but not with Internet Explorer.

The page counts from one to the value specified in a "count" parameter.

To add this servlet to the build, add "ServerPushServlet" to the dependency.groups and "com.qindesign.servlet.example.ServerPushServlet" to the reflect.classes build properties. Also be sure to add something suitable to the Servlet Configuration file.

[Top]

com.qindesign.servlet.example.TemplateDemoServlet
Demonstrates the servlet template engine. Templates are web pages that contain placeholders for dynamically generated data. For example, the template
Hello, #name#!
will print "Hello, " followed by the value of the variable named name (followed by "!").

This servlet lets you create, and dynamically interact with, your own template.

When using this servlet, be sure and set the include.templateEngine build property to true. Additional information can be found in the Template Guide.

To add this servlet to the build, add "TemplateDemoServlet" to the dependency.groups and "com.qindesign.servlet.example.TemplateDemoServlet" to the reflect.classes build properties. Also be sure to add something suitable to the Servlet Configuration file.

[Top]

com.qindesign.servlet.example.ToggleLEDServlet
Toggles the CPU status LED on the TINI board.

To add this servlet to the build, add "ToggleLEDServlet" to the dependency.groups and "com.qindesign.servlet.example.ToggleLEDServlet" to the reflect.classes build properties. Also be sure to add something suitable to the Servlet Configuration file.

[Top]