Servlet (Interface Manipulation Package)

[using it]

Interface Manipulation Package v4.0 (2008-06-25)

©copyright

imp.util
Class Servlet

java.lang.Object
  imp.util.Servlet

public abstract class Servlet
extends Object
extends Object

Defines a servlet on the local host.

In this context, a servlet is a minimal service receiving queries and answering via an XML string.

This mechanism is based on a multi-client/server socket connections, with UTF-8 char-sequences transport and eventually uses a Secure Sockets Layer (SSL) protocol (if and only if the javax.net.ssl.keyStore or javax.net.ssl.trustStore parameter is defined).

In a web mechanism it is usable both on the server and clients sides

Using the SSL mechanism

Generates a certificate (where the public-keystore-password is defined) using:
keytool -genkey -keyalg RSA -keystore <key-file>
Run the servlet using:
$java -Djavax.net.ssl.keyStore=<key-file> -Djavax.net.ssl.keyStorePassword=<public-keystore-password> imp.util.Servlet start ..
Run the application client (or the servlet stop request) using:
$java -Djavax.net.ssl.trustStore=<key-file> -Djavax.net.ssl.trustStorePassword=<public-keystore-password> ..

(the parameters -Djava.protocol.handler.pkgs=com.sun.net.ssl.internal.www.protocol -Djavax.net.debug=ssl defines a verbose mode).

Advising how to use SSL ``keys''. The SSL authentication is based on the knowledge of a key.

- The key must NOT be stored in a data or software code file, but generated following the SSL authentication mechanism it must NOT be shared with other persons.

- The key is to be an every day sentence, with, say, some spell mistake and punctuation e.g. [. . too be or not to bee!.

- If the key is to be propagated via email, we recommend to do it in two steps: (i) send the key sentence, within a standard text; (ii) send an independent mail (with a different subject, if possible from another sender) with an explanation about (i)

The security manifest. Here the idea is that:

- hackers (interested to crack the system but not interested in its contents) will not have much fun to crack this secured mechanism because it is based on very standard mechanisms, hackers have already played with,

- intruders (interested to crack the system because of its contents) may crack the system (thanks to hackers) but this violation will be very easily detected, and the intruder's origin detected.

Tiny and standard servlet. With respect to standard http-servlet this mechanism is to be used:

- to test a servlet algorithm in a separate environment avoiding any conflict and risk of deny of service,

- instead of a http-servlet server when only one servlet is to be used (e.g. remote access and control of a device),

- inside a browser applet, when this applet has to react to external events (security restrictions being taken into account).

Method Summary
`static boolean`	`check(int port)` Check if the servlet is running on the local host without any error.
`static String`	`getQuery(String host, int port, Value query, boolean close)` Gets a query from a given servlet.
`static void`	`main(String[] arguments)` Starts/stops/calls a servlet on the local host.
`abstract String`	`query(Value query)` Defines the treatment of a query by the servlet.
`void`	`start(int port)` Starts the servlet on the local host and block until the service is stopped.
`void`	`stop()` Stops the servlet.
`static int[]`	`toBuffer(String string)` Decodes a numerical buffer from a String.
`static String`	`toString(int[] buffer)` Encodes a numerical buffer into a String.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

check

public static boolean check(int port)
                     throws IOException

Check if the servlet is running on the local host without any error.

Parameters:: port - Servlet port.
Returns:: True if the servlet is running, false otherwise.
Throws:: IOException - If an exception occurs.

getQuery

public static String getQuery(String host,
                              int port,
                              Value query,
                              boolean close)
                       throws IOException

Gets a query from a given servlet.

Parameters:: host - [optional, default is null] The host-name or IP number where the remote-imp service runs, the "localhost" or the null value corresponds to the local host.; port - [optional, default is added to the host-name] Port number for the remote connection (value should be higher than 10000). It can also be specified with the host-name using the <host-name>:<port> construct.; query - [optional, default is null or added to the host-name] The parameters of the query.
As String:
The parameter query specified as XML string. It can also be specified with host-name using the <host-name>:<port>?<name>=<value&.. URL encoded construct.; close - [optional, default is true] If true the connection is closed after this query, else it remains open for a next query.
Throws:: IOException - If an I/O exception has occurred when starting the channel.

main

public static void main(String[] arguments)

Starts/stops/calls a servlet on the local host.

Usage: $JAVA imp.util.Servlet start <servlet-class-name> <port> to construct and start the given servlet on the given port.

Usage: $JAVA imp.util.Servlet stop <port> to stop any servlet on the given port.

Usage: $JAVA imp.util.Servlet query [<host>] <port> <query> to make a query to an existing servlet.

Usage: $JAVA imp.util.Servlet new <servlet-class-name> <query> to make once a query on a local servlet without any connection.

Usage: $JAVA imp.util.Servlet to test the servlet mechanism on the local host.

query

public abstract String query(Value query)
                      throws Exception

Defines the treatment of a query by the servlet.

Parameters:: query - The input query.
As String:
The input query as an XML string.
Returns:: The query answer which is, by contract, either an XML construct or the empty string "". Returning null closes the connection.
Throws:: Exception - If the query treatment fails.

start

public void start(int port)
           throws IOException

Starts the servlet on the local host and block until the service is stopped.

The new Thread(new Runnable() { public void run() { try { servlet.start(port); } catch(.. }).start(); construct allows to start in non-blocking mode.

Parameters:: port - Port number for the remote connection (value should be higher than 10000).
Throws:: IOException - If an I/O exception has occurred when starting the server.; BindException - If the port is already in use (likely another servlet is running on this port).; IllegalArgumentException - If the port number is illegal (lower than 10000).

stop

public void stop()

Stops the servlet.

toBuffer

public static int[] toBuffer(String string)

Decodes a numerical buffer from a String.

Parameters:: string - The string encoding the numerical buffer.
Returns:: The decoded buffer.

toString

public static String toString(int[] buffer)

Encodes a numerical buffer into a String.

Parameters:: buffer - The numerical buffer.
Returns:: A string so that toBuffer(toString(buffer)) allows to recover the buffer.

imp.util Class Servlet