This memo documents the protocol used to communicate with an I*Tea application server. This protocol is intended for CGI adapters to interface with a "stand alone" I*Tea server process, hence the name of "I*Tea adapter protocol". I*Tea runs in a main loop accepting TCP/IP connections on a configured port. For each accepted connection I*Tea does the following: 1 - reads request data. 2 - processes the data and generates response headers and content. 3 - sends the response back through the same connection. 4 - closes its side of the connection. An I*Tea request is represented by a set of text lines with information on the originating HTTP request. Each line contains a "property=value" data and is terminated by an end-of-line marker. The request is ended by a blank line (just an end-of-line marker). The end-of-line marker is the character '\n' (10 DEC) or the character sequence '\r\n' (13,10 DEC). Character set encoding depends on the JVM configuration where I*Tea is installed. It is usually safe to assume ISO_8859_1. Acceptable property names and values are: Header.Cookie - contents of CGI environment variable HTTP_COOKIE. Request.script-name - contents of CGI environment variable SCRIPT_NAME. Server.path-info - contents of CGI environment variable PATH_INFO. Server.path - contents of CGI environment variable PATH_TRANSLATED. Server.ip - contents of CGI environment variable REMOTE_ADDR. Server.url - contents of CGI environment variable SERVER_URL. Server.protocol - One of "http" or "https" (without the quotes). Server.name - contents of CGI environment variable SERVER_NAME. Server.port - contents of CGI environment variable SERVER_PORT. Server.userAgent - contents of CGI environment variable HTTP_USER_AGENT. Form.fieldname - value of the form field with name "fieldname". Upload.filekey - upload path of uploaded file with key "filekey". The "filekey" if the field name of the Form file upload field. Note that there is no difference between a POST and a GET HTTP request when converted to the I*Tea adapter protocol. The order of these properties does not matter, except that if more than one form field has the same name, the value that prevails is the last one. Form field values must be in plain text. The encoding of field values specified by CGI must be decoded before sending to I*Tea. (ie. '+' characters must be converted to spaces, '%xx' must be converted to a single character, etc...) If the special characters '\\', '\n', '\r', '\t' occur in a field value, they must be encoded just like the C convention used here to represent these characters (without the enclosing ''). If there are no form field values in the originating HTTP request, no "Form.fieldname=xxx" lines should be sent. Uploaded files are sent in UUENCODE format after the blank line. The uuencodedfile name is the basename for the file upload path. If there are no files to upload, no data should be sent after the blank line. No "Upload.filekey=xxx" lines can be sent in the request either. After the request is processed, I*Tea answers the request on the same connection. The response properties are sent back in the same format, "property=value". Lines are separated according to the JVM configuration in use where I*Tea is installed. On UNIX machines, only '\n' is used. On MS-Windows, '\r', '\n' is used. Documented properties are: Response.ContentType - Value for a "Content-Type: " HTTP header. Response.Location - Value for a "Location: " HTTP header. Response.Cookie - Value for a "Set-Cookie: " HTTP header. A blank line follows and the response content is sent after. Note that the content might be binary data. I*tea then closes its side of the socket, and expects the adapter to do the same. Example of a request resulting from posting a form with fields "username", "password", and "text" ("text" has two lines of content): ------------------------------------------------------------- Header.Cookie=LJC-COL-DVLP=2843760151 Request.script-name=/ljc/col Server.path-info=/Saida.tea Server.path=/opt/develop/col/develop/www/docs/Saida.tea Server.ip=192.168.30.14 Server.name=gold.solsuni.pt Server.port=12220 Server.userAgent=Mozilla/4.6 [en] (X11; I; SunOS 5.6 sun4u) Server.protocol=http Form.username=op59307 Form.password=123456 Form.text=line1\r\nline2 ------------------------------------------------------------- Example of a reponse setting a cookie and with HTML content: ------------------------------------------------------------- Response.ContentType=text/html Response.Cookie=LJC-COL-DVLP=2843760151; path=/ ... ------------------------------------------------------------- Example of a response with HTTP re-direction: ------------------------------------------------------------- Response.ContentType=text/html Response.Location=http://red.pdmfc.com:12220/ljc/index.html ------------------------------------------------------------- No examples are (yet) available with file upload. ( The source of two C implementations of CGI adapters using this protocol are included with the full release of I*Tea downloadable from http://www.pdmfc.com/itea )