HTTP Service User's Guide

Version 3.0.4

Last updated: Decembmer 9, 2011

Table of Contents

Description

The HTTP service is an external STAF service that provides the ability to quickly and easily make HTTP requests. These requests can be grouped together in a session. Performing requests in a session provides the ability simulate a browsing experience. Since a session provides memory about the last request it is possible to manipulate cookies, login into secure http sites, and interact with form and link html elements that are returned from requests.

Software Requirements

This service requires:

Installation and Configuration

Install the HTTP service by downloading the HTTPV304.zip/tar file from Get STAF Services and extracting its contents to a local directory (e.g. C:\STAF\services or /usr/local/staf/services). The STAFHTTP.jar file is the service jar file needed when registering the HTTP service.

The HTTP service is an external STAF service written in Java. Since it is an external service, it must be registered with a SERVICE configuration statement in the STAF configuration file (or it can be dynamically registered using the SERVICE service's ADD SERVICE request).

The syntax to register the service is: 

SERVICE <Service Name> LIBRARY JSTAF EXECUTE <Service Jar File Name>

<Service Name> is the name by which the HTTP service will be known on this machine.

<Service Jar File Name> is the fully-qualified name of the STAFHTTP.jar file.

Examples

SERVICE Http LIBRARY JSTAF EXECUTE {STAF/Config/STAFRoot}/services/http/STAFHTTP.jar
SERVICE Http LIBRARY JSTAF EXECUTE C:/STAF/services/http/STAFHTTP.jar
SERVICE Http LIBRARY JSTAF EXECUTE /usr/local/staf/services/http/STAFHTTP.jar

Request Syntax 

OPEN    SESSION
CLOSE   SESSION <Session>
LIST    SESSIONS
LIST    <FORMS | LINKS | COOKIES | DEFAULTHEADERS | AUTHENTICATIONHOSTS |
        CONTROLNAMES FORM [NAME <Form Name> | ID <Id> | INDEX <Index>]>
        SESSION <Session>
QUERY   SESSION <Session>
GET     SESSION <Session> CONTENT [FILE <File Name> [TOMACHINE <Machine>]]

REQUEST METHOD <Http Method> URL <Target Url> [ENCODED] [CONTENT <Content>]
        [HEADER <Key>=<Value>]... [PARAMETER <Key>=<Value>]...
        [CONTENTFILE <Key>=<File Name>]...
        [FOLLOWREDIRECT | DONOTFOLLOWREDIRECT] [SESSION <Session>]
        [FILE <Filename> [TOMACHINE <Machine>]]
        [IGNOREERRORS] [NOSTATUS] [RETURNHEADERS] [RETURNNOCONTENT]
DOPOST  URL <Target Url> [ENCODED] [CONTENT <Content>]
        [HEADER <Key>=<Value>]... [PARAMETER <Key>=<Value>]...
        [CONTENTFILE <Key>=<File Name>]...
        [FOLLOWREDIRECT | DONOTFOLLOWREDIRECT] [SESSION <Session>]
        [FILE <Filename> [TOMACHINE <Machine>]]
        [IGNOREERRORS] [NOSTATUS] [RETURNHEADERS] [RETURNNOCONTENT]
DOGET   URL <Target Url> [ENCODED] [CONTENT <Content>]
        [HEADER <Key>=<Value>]... [PARAMETER <Key>=<Value>]...
        [FOLLOWREDIRECT | DONOTFOLLOWREDIRECT] [SESSION <Session>]
        [FILE <Filename> [TOMACHINE <Machine>]]
        [IGNOREERRORS] [NOSTATUS] [RETURNHEADERS] [RETURNNOCONTENT]

SET     <FOLLOWREDIRECT | DONOTFOLLOWREDIRECT> SESSION <Session>
SET     PARSECONTENT <Enabled | Disabled | AutoDetect> SESSION <Session>
SET     HTTPPROXYHOST <Host> [HTTPPROXPYPORT <Port>] SESSION <Session>

QUERY   AUTHENTICATIONHOST <Host> SESSION <Session>
SET     AUTHENTICATIONHOST <Host> AUTHENTICATIONUSER <User>
        [AUTHENTICATIONPASSWORD <Password>] [AUTHENTICATIONDOMAIN <Domain>]
        SESSION <Session>
DELETE  AUTHENTICATIONHOST <Host> SESSION <Session>

QUERY   DEFAULTHEADER <Key> SESSION <Session>
SET     DEFAULTHEADER <Key> VALUE <Value> SESSION <Session>
DELETE  DEFAULTHEADER <Key> SESSION <Session>

QUERY   COOKIE NAME <Name> SESSION <Session>
SET     COOKIE <NAME <Name> VALUE <Value>> | <POLICY <policy>>
        SESSION <Session>
DELETE  COOKIE NAME <Name> SESSION <Session>

QUERY   FORM [NAME <Form Name> | ID <Id> | INDEX <Index>] [CONTROLNAME <Name>]
        SESSION <Session>
SET     FORM [NAME <Form Name> | ID <Id> | INDEX <Index>]
        CONTROLNAME <Name> VALUE <Value> SESSION <Session>
SUBMIT  FORM [NAME <Form Name> | ID <Id> | INDEX <Index>] SESSION <Session>
        [FOLLOWREDIRECT | DONOTFOLLOWREDIRECT]
        [FILE <Filename> [TOMACHINE <Machine>]]
        [IGNOREERRORS] [NOSTATUS] [RETURNHEADERS] [RETURNNOCONTENT]
RESET   FORM [NAME <Form Name> | ID <Id> | INDEX <Index>] SESSION <Session>

QUERY   LINK <NAME <Name> | ID <Id> | INDEX <Index>> SESSION <Session>
FOLLOW  LINK <NAME <Name> | ID <Id> | INDEX <Index>> SESSION <Session>
        [FOLLOWREDIRECT | DONOTFOLLOWREDIRECT]
        [FILE <Filename> [TOMACHINE <Machine>]]
        [IGNOREERRORS] [NOSTATUS] [RETURNHEADERS] [RETURNNOCONTENT]

HELP

VERSION

Session Management

OPEN SESSION

This command opens a new web session. It returns the session id of the new session. The owner of the new session is identified by the machine, process, and handle used to issue the OPEN command.

Syntax

OPEN    SESSION

SESSION specifies to open a new session.

Security

This command requires trust level 3 or higher.

Results

If successful, the result buffer will contain the id of the new session.

Examples

CLOSE SESSION

This command closes a session. This is automatically done when the HTTP service is terminated. Once a session is closed it is no longer accessible. The session id is recycled for the next OPEN request.

Syntax

CLOSE   SESSION <Session>

SESSION specifies the id of the session to close. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 5 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

LIST SESSIONS

This command will list all the sessions that are currently open.

Syntax

LIST    SESSIONS

SESSIONS specifies to list the sessions that are currently open.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain a marshalled <List> of <Map:STAF/Service/HTTP/ListSession> representing a list of the sessions that are currently open. The map is defined as follows:

Definition of map class STAF/Service/HTTP/ListSession
Description: This map class represents summary information for a Http session.
Key Name Display Name Type Format / Value
sessionID ID <String>
url Url <String> | <None>
title Title <String> | <None>
Notes:
  1. The "ID" value is set to the ID of the session.
  2. The "Url" value is set to the url of the current page in the session, or <None> if the session isn't set to a page.
  3. The "Title" value is set to the title for the current page in the session, or <None> if the page doesn't have one.

Examples

QUERY SESSION

This command returns information regarding a session.

Syntax

QUERY   SESSION <Session>

SESSION specifies the id of the session to be queried. This option will resolve variables.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain a marshalled <Map:STAF/Service/HTTP/Session> representing a list of the links in the specified page of the specified session. The maps are defined as follows:

Definition of map class STAF/Service/HTTP/Session
Description: This map class represents detailed information for a Http session.
Key Name Display Name Type Format / Value
url Url <String> | <None>
title Title <String> | <None>
statusCode Status Code <String>
statusMessage Status Message <String> | <None>
cookiePolicy Cookie Policy <String>
followsRedirects Follows Redirects <String> | <None> 'Enabled' | 'Disabled'
parseContent Parse Content <String> | <None> 'Enabled' | 'Disabled' | 'AutoDetect'
httpProxyHost HTTP Proxy Host <String> | <None>
httpProxyPort HTTP Proxy Port <String> | <None>
owner Owner <Map>:STAF/Service/HTTP/SessionOwner
Notes:
  1. The "Url" value is set to the url of the current page in the session, or <None> if the session isn't set to a page.
  2. The "Title" value is set to the title for the current page in the session, or <None> if the page doesn't have one.
  3. The "Status Code" value is set to HTTP status code for the last HTTP request made in the session.
  4. The "Status Message" value is set to HTTP message for the last HTTP request mode in the session.
  5. The "Cookie Policy" value indicates the default cookie policy for the session.
  6. The "Follows Redirects" value indicates the default behavior for following redirects for the session.
  7. The "Parse Content" value indicates the default behavior for parsing the content as HTML for the session.
  8. The "HTTP Proxy Host" value indicates the HTTP proxy host for the session or <None> if no HTTP proxy host has been set.
  9. The "HTTP Proxy Port" value indicates the HTTP proxy port for the session or <None> if no HTTP proxy host has been set.
  10. The "Owner" value is set to a map containing information about the owner of the session (the process that opened the session).

Definition of map class STAF/Service/HTTP/SessionOwner
Description: This map class represents information about the owner of a Http session.
Key Name Display Name Type Format / Value
instanceUUID Instance UUID <String>
machine Machine <String>
handleName Handle Name <String> | <None>
handle Handle <String>
Notes:
  1. The "Instance UUID" value is set to the STAF instance UUID that opened the session.
  2. The "Machine" value is set to the machine that opened the session.
  3. The "Handle Name" value is set to name of the handle of the process that opened the session, or <None> if the process doesn't have a handle name.
  4. The "Handle" value is set to handle number of the process that opened the session.

Examples

GET SESSION CONTENT

This command returns the content from the last http request or redirection. It does not show any changes made to forms in the page through the use of the FORM commands. This is the content that is visible in the browser.

Syntax

GET     SESSION <Session> CONTENT [FILE <File Name> [TOMACHINE <Machine>]]

SESSION specifies the id of the session. This option will resolve variables.

CONTENT specifies to get the content from the last http request or redirection.

FILE specifies the fully-qualified name of a file where the response should be stored. If the FILE option is not specified, the response will be returned in the STAF result buffer. If an error occurs writing to the file, an error will be generated and the response will be returned in the result buffer. An error will occur if the parent directory for the file does not exist. This option will resolve variables.

TOMACHINE specifies the machine where the output file should be stored. The output file will be stored on the HTTP service machine if this option is not specified. This option will resolve variables.

Security

This command requires trust level 3 or higher.

Also, if option TOMACHINE is specified, the HTTP service machine requires trust level 4 on the target machine in order to copy the file from the HTTP service machine to the target machine.

Results

If successful, the result buffer will be a string containing the response body of the last request or redirection, unless the FILE option is specified.

Examples

SET SESSION FOLLOWREDIRECT

This command sets the default behavior for following redirects for a session. A possible redirect occurs when an HTTP return code of 3XX is encountered. When following redirects is enabled, the HTTP service will follow up to 100 redirects, after that point it is assumed that an inadvertant infinite loop has been entered and return an error.

Syntax

SET     <FOLLOWREDIRECT | DONOTFOLLOWREDIRECT> SESSION <Session>

FOLLOWREDIRECT specifies the session should attempt to follow any 3XX return codes it gets from attempting the request. The contents of the result buffer will contain the result of the last redirect followed.

DONOTFOLLOWREDIRECT specifies the session should not attempt to follow any 3XX return codes it gets from attempting the request.

SESSION specifies the id of the session. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

SET SESSION PARSECONTENT

This command sets the default behavior for whether to parse the contents for a session as HTML. Parsing the content as HTML means that the HTTP service will scan/parse all the HTML tags in the content gathering information that allows you to submit additional requests to list/query links and/or forms in the HTML content. For performance/memory-usage reasons, this parsing should only be done when the content is an HTML document (not when the content is binary data, etc).

Syntax

SET     PARSECONTENT <Enabled | Disabled | AutoDetect> SESSION <Session>

PARSECONTENT specifies whether the session should parse new content it gets (e.g. on a DOGET request) as HTML. This option will resolve variables. The valid values (case-insensitive) that can be specified are:

SESSION specifies the id of the session. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

SET SESSION HTTPPROXYHOST

This command sets an HTTP proxy server for a session. A proxy server is a server that acts as an intermediary for requests from clients seeking resources from other servers.

Once a HTTP proxy server has been set for a session, you can change its settings but you cannot change it back to not using a HTTP proxy server for the rest of the session.

Syntax

SET HTTPPROXYHOST <Host> [HTTPPROXYPORT <Port>] SESSION <Session>

HTTPPROXYHOST specifies the host name or IP address of the HTTP proxy server that you want to use for the session. This option will resolve variables.

HTTPPROXYPORT specifies the port for the HTTP proxy server. It defaults to -1 which indicates to use the default port. Valid values are -1 to 65535. This option will resolve variables.

SESSION specifies the id of the session. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

Request Management

REQUEST

Generates and sends an HTTP request. Then returns the HTTP response in a variety of formats.

Syntax

REQUEST METHOD <Http Method> URL <Target Url> [ENCODED] [CONTENT <Content>]
        [HEADER <Key>=<Value>]... [PARAMETER <Key>=<Value>]...
        [CONTENTFILE <Key>=<File Name>]...
        [FOLLOWREDIRECT | DONOTFOLLOWREDIRECT] [SESSION <Session>]
        [FILE <Filename> [TOMACHINE <Machine>]]
        [IGNOREERRORS] [NOSTATUS] [RETURNHEADERS] [RETURNNOCONTENT]

METHOD specifies the HTTP method to be used in this request. This may be any of GET, POST, PUT, HEAD, OPTIONS, DELETE, or TRACE. This option will resolve variables.

URL specifies the host, port, and uri which should be used as the URL for this HTTP request. This should be of the format: 

 [protocol://][host][:port]/uri
The supported protocols are http and https. Note that http is the default if protocol is not specified. This option will resolve variables.

ENCODED specifies that the URL is already in an escaped-encoded (aka percent-encoded) form. If not specified, the URL is assumed to not be in an escaped-encoded form and URL encoding will be performed implicitly. This option is optional. Note that escaped-encoded means that the URL is using encoded sequences with format %<Hex><Hex> to represesent certain characters in the URL (e.g. %20 instead of a space, %26 instead of a &, %25 instead of a %, etc).

CONTENT specifies the content-body which should be sent with this request. This parameter will be ignored for GET, HEAD, OPTIONS, DELETE, or TRACE methods. This parameter is optional. This option will resolve variables using the IGNOREERRORS option when submitting a VAR RESOLVE request.

HEADER may be specified to include HTTP Headers in the request. The headers should be specified as key value pairs in the form key=value. This parameter is optional. This parameter may be specified more than once to set multiple headers. This option will resolve variables.

The following headers will be set by default: 
User-Agent: Jakarta Commons-HttpClient/3.1
Host: <host_url>
These headers may be overridden by specifying different values.

PARAMETER may be specified to include parameters in a request. The parameters should be specified as key value pairs in the form Parameter Name=Value. This option may be specified more than once to set multiple parameters. Only GET and POST requests can specify parameters. If this option is specified, CONTENT is ignored. This option will resolve variables. This option will handle private data in the Value specified for the parameter.

CONTENTFILE may be specified to include files in a request. The parameters should be specified as key value pairs in the form Parameter Name=File Name. This option may be specified more than once to set multiple files. Only POST requests can specify parameters. If this option is specified the service will attempt a multipart post using a binary file transfer. If this option is specified CONTENT is ignored. This option will resolve variables.

SESSION specifies the id of the session to perform the request on. This option will resolve variables.

FOLLOWREDIRECT specifies the session should attempt to follow any 3XX return codes it gets from attempting the request. This is a recursive process and will follow up to 100 redirects. This option will override the session setting. The contents of the result buffer will contain the result of the last redirect followed.

DONOTFOLLOWREDIRECT specifies the session should not attempt to follow any 3XX return codes it gets from attempting the request. This option will override the session setting.

FILE specifies the fully-qualified name of a file where the response should be stored. If the FILE parameter is not specified, the response will be returned in the STAF result buffer. If an error occurs writing to the file, an error will be generated and the response will be returned in the result buffer. An error will occur if the parent directory for the file does not exist. This option will resolve variables.

TOMACHINE specifies the machine that should be used to store the outputfile. The output file will be stored on the HTTP service machine if this option is not specified. This option will resolve variables.

IGNOREERRORS may be specified to indicate that HTTP client and server errors (HTTP status codes of 4XX and 5XX) should be ignored. The default is to return a non-zero STAF return code when an HTTP error is encountered. If this option is specified and an error occurs, the command will return a 0 code. However, the status code will still be returned, unless disabled. See the Return Codes section below for more information.

NOSTATUS may be specified to indicate that the HTTP response code and HTTP response message should not be returned in the result. Default is to include both of these values in the output.

RETURNHEADERS may be specified to indicate that all HTTP headers in the HTTP response should be returned with the result. Default is to not include headers in the output.

RETURNNOCONTENT may be specified to indicate that the HTTP response body should not be returned in the result. Default is to include it in the output.

Security

if option SESSION is not specified, this command requires trust level 3 or higher.

If option SESSION is specified, this command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Also, if option TOMACHINE is specified, the HTTP service machine requires trust level 4 on the target machine in order to copy the file from the HTTP service machine to the target machine.

Return Codes

If an HTTP Client or Server error occurs (HTTP Status code of 4XX or 5XX) and IGNOREERRORS was not specified, then the STAF return code will be 4000 plus the HTTP status code. For example, if the response had a status code of 501 the STAF return code would be 4501. All other return codes from REQUEST are documented in "HTTP Error Code Reference".

Results

If successful, the result buffer will contain a marshalled <Map:STAF/Service/HTTP/HttpResultMapClass> representing the output of the HTTP response upon completion. The map is defined as follows:

Definition of map class STAF/Service/HTTP/HttpResultMapClass
Description: This map class represents the output of the HTTP response upon completion.
Key Name Display Name Type Format / Value
statusCode Status Code <String>
statusMessage Status Message <String> | <None>
headers Headers <Map> | <None>
content Content <String> | <None>
Notes:
  1. The "Status Code" value is set to HTTP status code from the HTTP response, or <None> if NOSTATUS was specified in the request.
  2. The "Status Message" value is set to the HTTP status message from the HTTP response, or <None> if no message was provided or if NOSTATUS was specified in the request.
  3. The "Headers" value is set to a map containing all the HTTP headers in the HTTP response, or <None> if RETURNHEADERS was not specified in the request.
  4. The "Content" value is set to the HTTP response body, or <None> if RETURNNOCONTENT was specified in the request.

If the FILE parameter is specified, the "Content" value will be written to the file instead of the result buffer (the "Content" value will be <None> in the result buffer).

Examples

DOPOST

A DOPOST command is identical to a REQUEST METHOD post command. For example, the following two commands are identical:

DOGET

A DOGET command is identical to a REQUEST METHOD get command, except that CONTENTFILES is not allowed. For example, the following two commands are identical:

Preemptive Authentication Management

LIST AUTHENTICATIONHOSTS

This command lists all the authentication hosts in the current page of the specified session. When directed to a secure site that exists on a host in the authentication hosts list, the HTTP service will preemptively attempt to authenticate a secure session with the site using the user and password associated with the host. The HTTP service supports Basic, Digest, and NTLM authentication schemes.

Syntax

LIST    AUTHENTICATIONHOSTS SESSION <Session>

AUTHENTICATIONHOSTS specifies to list all the authentication hosts in the current page of the specified session.

SESSION specifies the id of the session with the authentication enabled hosts. This option will resolve variables.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain a marshalled <List> of <String> representing the authentication enabled hosts in the session.

Examples

QUERY AUTHENTICATIONHOST

This command provides information about a specific authentication host. When directed to a secure site that exists on a host in the authentication hosts list, the HTTP service will preemptively attempt to authenticate a secure session with the site using the user and password associated with the host. The HTTP service supports Basic, Digest, and NTLM authentication schemes.

Syntax

QUERY   AUTHENTICATIONHOST <Host> SESSION <Session>

AUTHENTICATIONHOST specifies the host to get information about. This option will resolve variables.

SESSION specifies the id of the session with the authentication enabled hosts. This option will resolve variables.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain a marshalled <Map:STAF/Service/HTTP/AuthenticationHost> representing the specified authentication enabled host in the session. The map is defined as follows:

Definition of map class STAF/Service/HTTP/AuthenticationHost
Description: This map class represents an authentication enabled host.
Key Name Display Name Type Format / Value
user User ID <String>
password Password <String> | <None> This data will be masked.
domain Domain <String> | <None>
Notes:
  1. The "Password" value will be displayed as ******* if a password was specified for the authentication host. Otherwise, the "Password" value is set to <None> if no password was specified.
  2. The "Domain" value is set to <None> if a domain was specified for the authentication host.

Examples

SET AUTHENTICATIONHOST

This command set the user and password of a authentication enabled host in the specified session. If the host is not in the authentication list, it will be added to the list. If it is in the list, the current values will be replaced.
The HTTP service supports Basic, Digest, and NTLM authentication schemes.

Warning: STAF does not encrypt its TCP communication, so the password will be sent in the clear to another STAF machine.

Syntax

SET     AUTHENTICATIONHOST <Host> AUTHENTICATIONUSER <User>
        [AUTHENTICATIONPASSWORD <Password>] [AUTHENTICATIONDOMAIN <Domain>] 
        SESSION <Session>

AUTHENTICATIONHOST specifies the host to be manipulated. This option will resolve variables.

AUTHENTICATIONUSER specifies the user to be associated with the host. This option will resolve variables.

AUTHENTICATIONPASSWORD specifies the password to be associated with the host. This option will resolve variables. This option will handle private data.

AUTHENTICATIONDOMAIN specifies the domain to be associated with the host. This is only used for NTLM authentication. This option will resolve variables.

SESSION specifies the id of the session with the authentication enabled host. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

DELETE AUTHENTICATIONHOST

This command removes a authentication enabled host from the specified session

Syntax

DELETE  AUTHENTICATIONHOST <Host> SESSION <Session>

AUTHENTICATIONHOST specifies the name of the authenticated host to be removed. This option will resolve variables.

SESSION specifies the id of the session with the authentication enabled host. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

Default Header Management

LIST DEFAULTHEADERS

This command lists all the default headers in the specified session

Syntax

LIST    DEFAULTHEADERS SESSION <Session>

DEFAULTHEADERS specifies to list all the default headers in the specified session.

SESSION specifies the id of the session with the default headers. This option will resolve variables.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain a <Map> representing the default header keys/values in the session.

Examples

QUERY DEFAULTHEADER

This command provides the value for a specific default header in the specified session.

Syntax

QUERY   DEFAULTHEADER <Key> SESSION <Session>

DEFAULTHEADER specifies the key of the default header about which to get information. This option will resolve variables.

SESSION specifies the id of the session with the default header. This option will resolve variables.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain the value for the specified default header key.

Examples

SET DEFAULTHEADER

This command sets the value of a default header in the specified session. If the specified default header does not exist, a new default header will be created and added to the session. If the default header does exist, the current value will be overwritten

Syntax

SET     DEFAULTHEADER <Key> VALUE <Value> SESSION <Session>

DEFAULTHEADER specifies the key of the default header to be manipulated. This option will resolve variables.

VALUE specifies that the new value of the default header. This option will resolve variables.

SESSION specifies the id of the session with the default header. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

DELETE DEFAULTHEADER

This command removes a default headers from the specified session

Syntax

DELETE  DEFAULTHEADER <Key> SESSION <Session>

DEFAULTHEADER specifies the name of the default header to be removed. This option will resolve variables.

SESSION specifies the id of the session with the default header. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

Cookie Management

LIST COOKIES

This command lists all cookies in the specified session

Syntax

LIST    COOKIES SESSION <Session>

COOKIES specifies to list all cookies in the specified session.

SESSION specifies the id of the session with the cookies. This option will resolve variables.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain a <List> of <String> representing the cookies in the session.

Examples

QUERY COOKIE

This command provides information about a specific cookie.

Syntax

QUERY   COOKIE NAME <Name> SESSION <Session>

COOKIE specifies to query a cookie.

NAME specifies the name of the cookie to be manipulated. This option will resolve variables.

SESSION specifies the id of the session with the cookie. This option will resolve variables.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain a marshalled <Map:STAF/Service/HTTP/Cookie> representing the specified cookie in the session. The map is defined as follows:

Definition of map class STAF/Service/HTTP/Cookie
Description: This map class represents a cookie.
Key Name Display Name Type Format / Value
value Cookie Value <String>
domain Domain <String> | <None>
path Path <String> | <None>
expirationDate Expiration Date <String> | <None>

Examples

SET COOKIE

This command sets the value of a cookie in the specified session

Syntax

SET     COOKIE <NAME <Name> VALUE <Value>> | <POLICY <policy>>
        SESSION <Session>
COOKIE specifies to set the value of a cookie.

NAME specifies the name of the cookie to be manipulated. This option will resolve variables.

VALUE specifies that the new value of the cookie. If the named cookie does not exist, a new cookie will be created and added to the session. This option will resolve variables.

POLICY specifies a new cookie policy for the session. Valid policy's are NETSCAPE, RFC2109, COMPATIBILITY, and IGNORE. The specification of any other policy will invoke HttpClient's default cookie policy, RFC2109. For more information on cookie policies see Http Client cookie information. This option will resolve variables.

SESSION specifies the id of the session with the cookie. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

DELETE COOKIE

This command removes a cookie from the specified session

Syntax

DELETE  COOKIE NAME <Name> SESSION <Session>
COOKIE specifies to remove a cookie.

NAME specifies the name of the cookie to be manipulated. This option will resolve variables.

SESSION specifies the id of the session with the cookie. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

Form Management

LIST FORMS

This command provides a list of the form elements in the current page of the specified session.

Syntax

LIST    FORMS SESSION <Session>
FORMS specifies to list all the form elements in the current page of the specified session.

SESSION specifies the id of the session containing the form. This option will resolve variables.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain a marshalled <List> of <Map:STAF/Service/HTTP/ListForm> representing a list of the forms for the specified page. The map is defined as follows:

Definition of map class STAF/Service/HTTP/ListForm
Description: This map class represents summary information for a form.
Key Name Display Name Type Format / Value
formIndex Index <String>
formID Form ID <String> | <None>
formName Form Name <String> | <None>
Notes:
  1. The "Index" value is set to index of the form.
  2. The "Form ID" value is set to the Id attribute for the form, or <None> if the form doesn't have one.
  3. The "Form Name" value is set to the name attribute for the form, or <None> if the form doesn't have one.

Examples

LIST FORM CONTROLNAMES

This command provides a list of the form control elements of the specified form in the current page of the specified session.

Syntax

LIST    CONTROLNAMES FORM [NAME <Form Name> | ID <Id> | INDEX <Index>] SESSION <Session Id>
CONTROLNAMES specifies to list the names of the form control elements of the specified form.

FORM specifies to list form control elements.

NAME identifies the name attribute to use to specify the form. If more than one form has the same name, the first form with the specified name will be selected. This option will resolve variables.

ID identifies the id attribute to use to specify the form. If more than one form has the same name, the first form with the specified id attribute will be selected. This option will resolve variables.

INDEX identifies the index of the form to be selected in the list of forms in the current page. This is a 1-based index. If no form is identified, the form at index 1 is selected. This option will resolve variables.

SESSION specifies the id of the session containing the form. This option will resolve variables.

If neither NAME, ID, or INDEX is specified, it defaults to the first form.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain a <List> of <String> representing a list of the form control names for the specified form on the specified page.

Examples

QUERY FORM

This command provides information about the specified form in the current page of the specified session.

Syntax

QUERY   FORM [NAME <Form Name> | ID <Id> | INDEX <Index>] [CONTROLNAME <Name>]
        SESSION <Session>
FORM specifies to query a form in current page of the specified session.

NAME identifies the name attribute to use to specify the form. If more than one form has the same name, the first form will be selected. This option will resolve variables.

ID identifies the id attribute to use to specify the form. If more than one form has the same name, the first form will be selected. This option will resolve variables.

INDEX identifies the index of the form to be selected in the list of forms in the current page. This is a 1-based index. If no form is identified, the form at index 1 is selected. This option will resolve variables.

CONTROLNAME identifies the form control to provide information about instead of the form in general. This option will resolve variables.

SESSION specifies the id of the session containing the form. This option will resolve variables.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain information about the specified form based on the options specified.

Examples

SET FORM

This command provides access to the form control elements in the current page of the specified session.

Syntax

SET     FORM [NAME <Form Name> | ID <Id> | INDEX <Index>]
        CONTROLNAME <Name> VALUE <Value> SESSION <Session>
FORM specifies to set a form control name.

NAME identifies the name attribute to use to specify the form. If more than one form has the same name, the first form will be selected. This option will resolve variables.

ID identifies the id attribute to use to specify the form. If more than one form has the same name, the first form will be selected. This option will resolve variables.

INDEX identifies the index of the form to be selected in the list of forms in the current page. This is a 1-based index. If no form is identified, the form at index 1 is selected. This option will resolve variables.

CONTROLNAME specifies the form control to set. In most cases, this is the name attribute of the control element. The exception is input elements of type checkbox, submit, and image. See Appendix A: Form Control Guide for more information. This option will resolve variables.

VALUE specifies the new value for the form control. See Appendix A: Form Control Guide for more information. This option will resolve variables. This option will handle private data.

SESSION specifies the id of the session containing the form. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

For more examples of setting control values for forms, see Appendix A: Form Control Guide.

SUBMIT FORM

This command submits a form from the current page in the specified session.

Syntax

SUBMIT  FORM [NAME <Form Name> | ID <Id> | INDEX <Index>] SESSION <Session>
        [FOLLOWREDIRECT | DONOTFOLLOWREDIRECT]
        [FILE <Filename> [TOMACHINE <Machine>]]
        [IGNOREERRORS] [NOSTATUS] [RETURNHEADERS] [RETURNNOCONTENT]
FORM specifies to submit form from the current page in the specifies session.

NAME identifies the name attribute to use to specify the form. If more than one form has the same name, the first form will be selected. This option will resolve variables.

ID identifies the id attribute to use to specify the form. If more than one form has the same name, the first form will be selected. This option will resolve variables.

INDEX identifies the index of the form to be selected in the list of forms in the current page. This is a 1-based index. If no form is identified, the form at index 1 is selected. This option will resolve variables.

SESSION specifies the id of the session containing the form. This option will resolve variables.

FOLLOWREDIRECT specifies the session should attempt to follow any 3XX return codes it gets from attempting the request. This is a recursive process and will follow up to 100 redirects. This option will override the session setting. The contents of the result buffer will contain the result of the last redirect followed.

DONOTFOLLOWREDIRECT specifies the session should not attempt to follow any 3XX return codes it gets from attempting the request. This option will override the session setting.

FILE specifies the fully-qualified name of a file where the response should be stored. If the FILE option is not specified, the response will be returned in the STAF result buffer. If an error occurs writing to the file, an error will be generated and the response will be returned in the result buffer. An error will occur if the parent directory for the file does not exist. This option will resolve variables.

TOMACHINE specifies the machine where the output file should be stored. The output file will be stored on the HTTP service machine if this option is not specified. This option will resolve variables.

IGNOREERRORS specifies that HTTP client and server errors (HTTP status codes of 4XX and 5XX) should be ignored. The default is to return a non-zero STAF return code when an HTTP error is encountered. If this option is specified and an error occurs, the command will return a 0 code. However, the status code will still be returned, unless disabled. See the Return Codes section of the REQUEST command for more information.

NOSTATUS specifies that the HTTP response code and HTTP response message should not be returned in the result. The default is to include both of these values in the output.

RETURNHEADERS specifies that all HTTP headers in the HTTP response should be returned with the result. The default is to not include headers in the output.

RETURNNOCONTENT specifies that the HTTP response body should not be returned in the result. The default is to include it in the output.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Also, if option TOMACHINE is specified, the HTTP service machine requires trust level 4 on the target machine in order to copy the file from the HTTP service machine to the target machine.

Results

If successful, the result buffer will contain the output of the HTTP response. The format of this output is described in the Results section for the REQUEST command.

Examples

RESET FORM

This command provides a way to reset the contents of a form in the current page of the specified session.

Syntax

RESET   FORM [NAME <Form Name> | ID <Id> | INDEX <Index>] SESSION <Session>
FORM specifies to reset the contents of a form.

NAME identifies the name attribute to use to specify the form. If more than one form has the same name, the first form will be selected. This option will resolve variables.

ID identifies the id attribute to use to specify the form. If more than one form has the same name, the first form will be selected. This option will resolve variables.

INDEX identifies the index of the form to be selected in the list of forms in the current page. This is a 1-based index. If no form is identified, the form at index 1 is selected. This option will resolve variables.

SESSION specifies the id of the session containing the form. This option will resolve variables.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Results

If successful, the result buffer will be empty.

Examples

Link Management

LIST LINKS

This command provides a list of the links elements in the current page of the specified session.

Syntax

LIST    LINKS SESSION <Session>

LINKS specifies to list the link elements on the current page of the specified session.

SESSION specifies the session id. This option will resolve variables.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain a marshalled <List> of <Map:STAF/Service/HTTP/ListLink> representing a list of the links in the specified page of the specified session. The map is defined as follows:

Definition of map class STAF/Service/HTTP/ListLink
Description: This map class represents summary information for a link.
Key Name Display Name Type Format / Value
linkIndex Index <String>
linkID Link ID <String> | <None>
linkName Link Name <String> | <None>
Notes:
  1. The "Index" value is set to index of the link.
  2. The "Link ID" value is set to the Id attribute for the link, or <None> if the link doesn't have one.
  3. The "Link Name" value is set to the name attribute for the link, or <None> if the link doesn't have one.

Examples

QUERY LINK

This command provides information about the specified link in the current page of the specified session.

Syntax

QUERY   LINK <NAME <Name> | ID <Id> | INDEX <Index>> SESSION <Session>

LINK specifies to query information about a link.

NAME specifies the name attribute of the link to follow in the current page. If more than one link has the same name, the first name will be selected. This option will resolve variables.

ID specifies the id attribute of the link to follow in the current page. This option will resolve variables.

INDEX specifies the index of the link to follow in the currenbt page. This is a 1-based index. This option will resolve variables.

SESSION specifies the session id. This option will resolve variables.

Security

This command requires trust level 2 or higher.

Results

If successful, the result buffer will contain a marshalled <Map:STAF/Service/HTTP/Link> representing the specified link in the session. The map is defined as follows:

Definition of map class STAF/Service/HTTP/Link
Description: This map class represents a link.
Key Name Display Name Type Format / Value
linkIndex Index <String>
linkID Link ID <String> | <None>
linkName Link Name <String> | <None>
href Href <String>
Notes:
  1. The "Index" value is set to index of the link.
  2. The "Link ID" value is set to the Id attribute for the link, or <None> if the link doesn't have one.
  3. The "Link Name" value is set to the name attribute for the link, or <None> if the link doesn't have one.
  4. The "Href" value is set to the link target Url.

Examples

FOLLOW LINK

This command changes the url of a session. It is equivalent to issuing a DOGET command with the URL value set to the href of the link.

Syntax

FOLLOW  LINK <NAME <Name> | ID <Id> | INDEX <Index>> SESSION <Session>
        [FOLLOWREDIRECT | DONOTFOLLOWREDIRECT]
        [FILE <Filename> [TOMACHINE <Machine>]]
        [IGNOREERRORS] [NOSTATUS] [RETURNHEADERS] [RETURNNOCONTENT]

LINK specifies to follow a link in the current page of the specified session.

NAME specifies the name attribute of the link to follow. If more than one link has the same name, the first name will be selected. This option will resolve variables.

ID specifies the id attribute of the link to follow. This option will resolve variables.

INDEX specifies the index of the link to follow. This is a 1-based index. This option will resolve variables.

SESSION specifies the id of the session. This option will resolve variables.

FOLLOWREDIRECT specifies the session should attempt to follow any 3XX return codes it gets from attempting the request. This is a recursive process and will follow up to 100 redirects. This option will override the session setting. The contents of the result buffer will contain the result of the last redirect followed.

DONOTFOLLOWREDIRECT specifies the session should not attempt to follow any 3XX return codes it gets from attempting the request. This option will override the session setting.

FILE specifies the fully-qualified name of a file where the response will be stored. If the FILE option is not specified, the response will be returned in the result buffer. If an error occurs writing to the file, an error will be generated and the response will be returned in the result buffer. An error will occur if the parent directory for the file does not exist. This option will resolve variables.

TOMACHINE specifies the machine where the output file will be stored. The output file will be stored on the HTTP service machine if this option is not specified. This option will resolve variables.

IGNOREERRORS specifies that HTTP client and server errors (HTTP status codes of 4XX and 5XX) should be ignored. The default is to return a non-zero STAF return code when an HTTP error is encountered. If this option is specified and an error occurs, the command will return a 0 code. However, the status code will still be returned, unless disabled. See the Return Codes section of the REQUEST command for more information.

NOSTATUS specifies that the HTTP response code and HTTP response message should not be returned in the result. The default is to include both of these values in the output.

RETURNHEADERS specifies that all HTTP headers in the HTTP response should be returned with the result. The default is to not include headers in the output.

RETURNNOCONTENT specifies that the HTTP response body should not be returned in the result. The default is to include it in the output.

Security

This command requires trust level 3 or higher for the session owner or requires trust level 4 for non-session owners.

Also, if option TOMACHINE is specified, the HTTP service machine requires trust level 4 on the target machine in order to copy the file from the HTTP service machine to the target machine.

Results

If successful, the result buffer will contain the output of the HTTP response. The format of this output is described in the Results section for the REQUEST command.

Examples

VERSION

VERSION displays the HTTP Service version.

Syntax

VERSION

Security

This request requires at least trust level 1.

Results

The result is the version number of the HTTP service.

Examples

HELP

HELP displays the request options and how to use them.

Syntax

HELP

Security

This request requires at least trust level 1.

Results

The result buffer contains the Help text for the request options for the HTTP service.

Examples

Session Examples

This section provides several examples of how the session functionality of the HTTP service can be leveraged.

The examples provided are submitting requests to the HTTP service from the command line, but the requests can also be submitted via a program (e.g. a shell script, Java program, etc).

Example 1: SSL Login Using Cookie Authentication and a Form

Demonstrates a SSL login using cookie authentication, and the use of a form to gather web based information. This example logs into the SourceForge website, so to run this example, you need a SourceForge user id.

  1. Open a new session: 
    C:\>STAF local HTTP OPEN SESSION
Response
--------
1

  2. Enable automatic redirection: 
    C:\>STAF local HTTP SET FOLLOWREDIRECT SESSION 1
Response
--------

  3. Login to SourceForge (replace the value for the form_loginname parameter with your userid and replace the value for the form_pw parameter with your password, using privacy delimiters to protect your password):

    C:\>STAF local HTTP DOPOST URL http://sourceforge.net/account/login.php PARAMETER form_loginname=user PARAMETER form_pw=!!@password@!! PARAMETER login=Login+With+SSL SESSION 1 RETURNNOCONTENT 

    Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : <None>

  4. Go to the STAF project webpage on SourceForge:

    C:\>STAF local HTTP DOGET URL http://sourceforge.net/projects/staf SESSION 1 RETURNNOCONTENT 

    Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : <None>

  5. Get a list of pending bugs:

    C:\>STAF local HTTP DOGET URL ../tracker/ PARAMETER group_id=33142 PARAMETER atid=407381 RETURNNOCONTENT SESSION 1 

    Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : <None>

    Note: The group_id and atid parameters used in this request can be obtained by going to the bug tracker for the STAF project. These parameters are used by SourceForge to index into the database and pull up the relevant entries to put in the displayed table.

  6. List the forms on this page and list the form controls for the form named "tracker_browse": 
    C:\>STAF local HTTP LIST FORMS SESSION 1
Response
--------
Index Form ID Form Name
----- ------- --------------
1     <None>  <None>
2     <None>  <None>
3     <None>  tracker_browse


C:\>STAF local HTTP LIST FORM NAME tracker_browse CONTROLNAMES SESSION 1
Response
--------
submit
group_id
atid
set
_assigned_to
_status
_category
_group
by_submitter
summary_keyword
order
sort

  7. Query the form controls named "_status", "sort", and "order" for the form named tracer_browse and look at their values. 
    C:\>STAF local HTTP QUERY FORM NAME tracker_browse CONTROLNAME _status SESSION 1
Response
--------
{
  Type           : select
  Disabled       : No
  Read Only      : No
  Value          : 1
  Possible Values: [
    100
    2
    3
    4
  ]
}

C:\>STAF local HTTP QUERY FORM NAME tracker_browse CONTROLNAME sort SESSION 1
Response
--------
{
  Type           : select
  Disabled       : No
  Read Only      : No
  Value          : DESC
  Possible Values: [
    ASC
  ]
}

C:\>STAF local HTTP QUERY FORM NAME tracker_browse CONTROLNAME order SESSION 1
Response
--------
{
  Type           : select
  Disabled       : No
  Read Only      : No
  Value          : artifact_id
  Possible Values: [
    priority
    summary
    open_date
    close_date
    submitted_by
    assigned_to
  ]
}

  8. De-select old values for the form controls named "_status", "sort", and "order":

    C:\>STAF local HTTP SET FORM NAME tracker_browse CONTROLNAME _status VALUE 1 SESSION 1
    Response
    --------


    C:\>STAF local HTTP SET FORM NAME tracker_browse CONTROLNAME sort VALUE DESC SESSION 1
    Response
    --------


    C:\>STAF local HTTP SET FORM NAME tracker_browse CONTROLNAME order VALUE artifact_id SESSION 1
    Response
    --------

  9. Select new values for the form controls named "_status", "sort", and "order":

    C:\>STAF local HTTP SET FORM NAME tracker_browse CONTROLNAME _status VALUE 4 SESSION 1
    Response
    --------


    C:\>STAF local HTTP SET FORM NAME tracker_browse CONTROLNAME sort VALUE ASC SESSION 1
    Response
    --------


    C:\>STAF local HTTP SET FORM NAME tracker_browse CONTROLNAME order VALUE open_date SESSION 1
    Response
    --------

  10. Verify the values for the form controls have been set: 
    C:\>STAF local HTTP QUERY FORM NAME tracker_browse CONTROLNAME _status SESSION 1
Response
--------
{
  Type           : select
  Disabled       : No
  Read Only      : No
  Value          : 4
  Possible Values: [
    100
    1
    2
    3
  ]
}

C:\>STAF local HTTP QUERY FORM NAME tracker_browse CONTROLNAME sort SESSION 1
Response
--------
{
  Type           : select
  Disabled       : No
  Read Only      : No
  Value          : ASC
  Possible Values: [
    DESC
  ]
}

C:\>STAF local HTTP QUERY FORM NAME tracker_browse CONTROLNAME order SESSION 1
Response
--------
{
  Type           : select
  Disabled       : No
  Read Only      : No
  Value          : open_date
  Possible Values: [
    artifact_id
    priority
    summary
    close_date
    submitted_by
    assigned_to
  ]
}

  11. Submit the form and store the results in a file on the local HTTP service machine: 
    C:\>STAF local HTTP SUBMIT FORM NAME tracker_browse SESSION 1 FILE C:\bugs.html
Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : <None>
    The C:\bugs.html file should be html file equivalent to acquiring the page in a browser.

  12. Close the session: 
    C:\>STAF local HTTP CLOSE SESSION 1
Response
--------

Example 2: Cookie Manipulation

This example demonstrates cookie manipulation.

  1. Open a new session: 
    C:\>STAF local HTTP OPEN SESSION
Response
--------
1

  2. Use Amazon's website to show cookie behavior. Amazon's homepage is permanently redirected, and the cookies are set at two points along the redirect. 
    C:\>STAF local HTTP SET FOLLOWREDIRECT SESSION 1
Response
--------


C:\>STAF local HTTP DOGET URL http://www.amazon.com RETURNNOCONTENT SESSION 1
Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : <None>

C:\>STAF local HTTP LIST COOKIES SESSION 1
Response
--------
session-id-time
session-id
obidos_path_continue-shopping
ubid-main

C:\>STAF local HTTP QUERY COOKIE NAME session-id SESSION 1
Response
--------
Cookie Value   : 002-0415776-6781616
Domain         : .amazon.com
Path           : /
Expiration Date: Sun Oct 31 02:00:00 CST 2004

C:\>STAF local HTTP QUERY SESSION 1
Response
--------
{
  Url              : http://www.amazon.com/exec/obidos/subst/home/home.html/002-0415776-6781616
  Title            : 
Amazon.com: Welcome

  Status Code      : 200
  Status Message   : OK
  Cookie Policy    : rfc2109
  Follows Redirects: Enabled
  Parse Content    : AutoDetect
  HTTP Proxy Host  : <None>
  HTTP Proxy Port  : <None>
  Owner            : {
    Instance UUID: 1C0BF447A40D00000929359C75636173
    Machine      : client1.austin.ibm.com
    Handle Name  : STAF/Client
    Handle       : 18
  }
}
    The end of the url should match the value of the session-id cookie.

  3. Open another session and use Amazon's website to show another example of cookie behavior: 
    C:\>STAF local HTTP OPEN SESSION
Response
--------
2

C:\>STAF local HTTP SET FOLLOWREDIRECT SESSION 2
Response
--------


C:\>STAF local HTTP SET COOKIE POLICY compatibility SESSION 2
Response
--------


C:\>STAF local HTTP DOGET URL http://www.amazon.com RETURNNOCONTENT SESSION 2
Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : <None>


C:\>STAF local HTTP LIST COOKIES SESSION 2
Response
--------
obidos_path_continue-shopping
session-id-time
session-id
    Note the missing cookie in the list from session 2.

  4. Set a cookie value: 
    C:\>STAF local HTTP SET COOKIE NAME session-id VALUE 000010001 SESSION 2
Response
--------


C:\>STAF local HTTP QUERY COOKIE NAME session-id SESSION 2
Response
--------
Cookie Value   : 000010001
Domain         : .amazon.com
Path           : /
Expiration Date: Sun Oct 31 02:00:00 CST 2004

  5. Add a cookie: 
    C:\>STAF local HTTP SET COOKIE NAME new_cookie VALUE new SESSION 2
Response
--------


C:\>STAF local HTTP LIST COOKIES SESSION 2
Response
--------
obidos_path_continue-shopping
session-id-time
session-id
new_cookie


C:\>STAF local HTTP QUERY COOKIE NAME new_cookie SESSION 2
Response
--------
Cookie Value   : new
Domain         : <None>
Path           : <None>
Expiration Date: <None>

  6. Close the sessions: 
    C:\>STAF local HTTP CLOSE SESSION 1
Response
--------


C:\>STAF local HTTP CLOSE SESSION 2
Response
--------

Example 3: Using Default Headers

This example demonstrates the use of default headers.

  1. Open a session: 
    C:\>STAF local HTTP OPEN SESSION
Response
--------
1

  2. Set a pair of headers to be sent with each request: 
    C:\>STAF local HTTP SET DEFAULTHEADER myName VALUE Bob SESSION 1
Response
--------


C:\>STAF local HTTP SET DEFAULTHEADER age VALUE 23 SESSION 1
Response
--------

  3. Verify that the STAF SourceForge web site supports TRACE: 
    C:\>STAF local HTTP REQUEST METHOD options URL http://staf.sourceforge.net RETURNHEADERS
Response
--------
{
  Status Code   : 200
  Status Message: OK
  Headers       : {
    Allow         : GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, PATCH, PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK, TRACE
    Connection    : close
    Content-Length: 0
    Date          : Thu, 03 Apr 2008 19:13:16 GMT
    Server        : Apache/1.3.33 (Unix) PHP/4.3.10
    X-Pad         : avoid browser bug
  }
  Content       :
}

  4. Check what headers are received when requests are made: 
    C:\>STAF local HTTP REQUEST METHOD trace URL http://staf.sourceforge.net SESSION 1
Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : TRACE / HTTP/1.1
age: 23
Host: staf.sourceforge.net
myName: Bob
User-Agent: Jakarta Commons-HttpClient/3.1
    This should show that you sent a header myName: Bob and a header age: 23.

  5. Override the default headers on a request: 
    C:\>STAF local HTTP REQUEST METHOD trace URL http://staf.sourceforge.net SESSION 1 HEADER age=21
Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : TRACE / HTTP/1.1
age: 21
Host: staf.sourceforge.net
myName: Bob
User-Agent: Jakarta Commons-HttpClient/3.1
    This should show that you set a header myName: Bob and a header age: 21.

  6. Send an additional header with your request: 
    C:\>STAF local HTTP REQUEST METHOD trace URL http://staf.sourceforge.net SESSION 1 HEADER job=admin
Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : TRACE / HTTP/1.1
age: 23
Host: staf.sourceforge.net
job: admin
myName: Bob
User-Agent: Jakarta Commons-HttpClient/3.1
    This should show that you sent headers myName: Bob, age: 23, and job: admin. The default header values are unaffected by the previous request.

  7. Change the header age: 
    C:\>STAF local HTTP SET DEFAULTHEADER age VALUE 25 SESSION 1
Response
--------


C:\>STAF local HTTP REQUEST METHOD trace URL http://staf.sourceforge.net SESSION 1
Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : TRACE / HTTP/1.1
age: 25
Host: staf.sourceforge.net
myName: Bob
User-Agent: Jakarta Commons-HttpClient/3.1
    This should show that you sent headers myName: Bob, and age: 25.

  8. Stop sending the age header: 
    C:\>STAF local HTTP DELETE DEFAULTHEADER age SESSION 1
Response
--------


C:\>STAF local HTTP REQUEST METHOD trace URL http://staf.sourceforge.net SESSION 1
Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : TRACE / HTTP/1.1
Host: staf.sourceforge.net
myName: Bob
User-Agent: Jakarta Commons-HttpClient/3.1
    This should show that you sent one header myName: Bob.

  9. Set myNames to be a multi-value header: 
    C:\>STAF local HTTP SET DEFAULTHEADER myNames VALUE "Bob, Sam, George" SESSION 1
Response
--------


C:\>STAF local HTTP REQUEST METHOD trace URL http://staf.sourceforge.net SESSION 1
Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : TRACE / HTTP/1.1
Host: staf.sourceforge.net
myName: Bob
myNames: Bob, Sam, George
User-Agent: Jakarta Commons-HttpClient/3.1
    This should show that you sent one header myNames: Bob, Sam, George.

  10. Close the session: 
    C:\>STAF local HTTP CLOSE SESSION 1
Response
--------

Example 4: Using Links

This example demonstrates the use of links.

  1. Open a session: 
    C:\>STAF local HTTP OPEN SESSION
Response
--------
1

  2. Go to your test site:

    C:\>STAF local HTTP DOGET URL ais.austin.ibm.com/content/Other/test/testHTTP.html RETURNNOCONTENT SESSION 1 

    Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : <None>
  3. Get a list of links on the page: 
    C:\>STAF local HTTP LIST LINKS SESSION 1
Response
--------
Index Link ID Link Name
----- ------- ---------
1     tamu    <None>
2     chi     <None>
3     csdl    <None>

  4. Check the url of one with id tamu: 
    C:\>STAF local HTTP QUERY LINK ID tamu SESSION 1
Response
--------
Index    : 1
Link ID  : tamu
Link Name: <None>
Href     : http://www.tamu.edu/

  5. Follow the link: 
    C:\>STAF local HTTP FOLLOW LINK ID tamu SESSION 1 RETURNNOCONTENT
Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : <None>
    Verify the link went where it was supposed to go: 
    C:\>STAF local HTTP QUERY SESSION 1
Response
--------
{
  Url              : http://www.tamu.edu/
  Title            : Texas A&M University - College Station
  Status Code      : 200
  Status Message   : OK
  Cookie Policy    : rfc2109
  Follows Redirects: Disabled
  Parse Content    : AutoDetect
  HTTP Proxy Host  : <None>
  HTTP Proxy Port  : <None>
  Owner            : {
    Instance UUID: 1C0BF447A40D00000929359C75636173
    Machine      : client1.austin.ibm.com
    Handle Name  : STAF/Client
    Handle       : 18
  }
}
    This has the same effect as a doget to the href of the link: 
    C:\>STAF local HTTP DOGET URL http://www.tamu.edu SESSION 1 RETURNNOCONTENT
Response
--------
Status Code   : 200
Status Message: OK
Headers       : <None>
Content       : <None>
    Verify the link went to the same place as the FOLLOW LINK command: 
    C:\>STAF local HTTP QUERY SESSION 1
Response
--------
{
  Url              : http://www.tamu.edu/
  Title            : Texas A&M University - College Station
  Status Code      : 200
  Status Message   : OK
  Cookie Policy    : rfc2109
  Follows Redirects: Disabled
  Parse Content    : AutoDetect
  HTTP Proxy Host  : <None>
  HTTP Proxy Port  : <None>
  Owner            : {
    Instance UUID: 1C0BF447A40D00000929359C75636173
    Machine      : client1.austin.ibm.com
    Handle Name  : STAF/Client
    Handle       : 18
  }
}

  6. Close the session: 
    C:\>STAF local HTTP CLOSE SESSION 1
Response
--------

HTTP Error Code Reference

In addition to the common STAF return codes, the following HTTP return codes are defined:

Table 1. HTTP Service Return Codes

Error Code Meaning Comment
4001 Unknown Host Error The specified host could not be found in the naming service.
4002 Connect Error The host was located, but a connection could not be made to the specified port.
4003 Invalid Method The specified method is not allowed. Allowed methods: POST, PUT, GET, HEAD, OPTIONS, DELETE, and TRACE.
4004 IO Exception The host was located, but an IO exception occurred opening a connection to the URL.
4005 Out of Memory Error Trying to get content that is too large. Recommend redirecting the content to a file using the FILE option or, if the content is not needed, you may be able to specify the RETURNNOCONTENT option depending on the request.
44XX
45XX		 HTTP Errors The Http request generated an HTTP error. The HTTP error code is the last 3 digits of the error code. See section 10 in RFC 2616 for an explanation of HTTP return codes (e.g. 404, 501, etc).

Appendix A: Form Control Guide

This section is intended to provide detailed information about interacting with the specific form control types.

For more information on HTML form controls, see the World Wide Web Consortium (W3C) website.

Getting Control Identifiers

Getting a list of control identifiers for a form is done with the LIST FORM CONTROLNAMES command. See section LIST FORM CONTROLNAMES for more information.

Getting Control Values

Getting the current value of a form control is done with the QUERY FORM CONTROLNAME command. See section QUERY FORM for more information.

Setting Control Values

Setting the value of an existing control is done using the SET FORM CONTROLNAME command. See section SET FORM for more information.

Notes:

  1. Control identifiers and values are case sensitive.

  2. Disabled controls cannot be accessed. The values of read-only controls cannot be set, but they will be sent with the submission of the form.

  3. HTTP service form controls recognize the following attributes:

Control Types

Here are some of the control types:

TEXTAREA

This control type corresponds to HTTP elements identified by <textarea> tags.

Service Request Options:

Example:

    HTML : 
      <textarea name=textarea_1>Mary had a little lamb</textarea>
    Service : 
      SET FORM form_1 CONTROLNAME textarea_1 VALUE "Mary had a little lamb."
    HTTP :
      textarea_1=Mary+had+a+little+lamb

INPUT type CHECKBOX

This control type corresponds to HTTP elements identified by <input type=checkbox> tags.

Service Request Options:

Example:

    HTML : 
      <input type=checkbox name=checkbox_1 value=check_1 checked/>
      <input type=checkbox name=checkbox_1 value=check_2 />
      <input type=checkbox name=checkbox_2 checked />
    Service : 
      SET FORM form_1 CONTROLNAME checkbox_1=check_1 VALUE checked
      SET FORM form_1 CONTROLNAME checkbox_1=check_2 VALUE unchecked
      SET FORM form_1 CONTROLNAME checkbox_2= VALUE checked
    HTTP : 
      checkbox_1=check_1&checkbox_2=

INPUT type RADIO

This control type corresponds to HTTP elements identified by <input type=radio> tags.

Service Request Options:

Example:

    HTML : 
      <input type=radio name=radio_1 value=option_1 checked/>
      <input type=radio name=radio_1 value=option_2 />
    Service : 
      SET FORM form_1 CONTROLNAME radio_1 VALUE option_1
    HTTP : 
      radio_1=option_1
Note: Only one radio control with a given name can be selected at a time.

INPUT type SUBMIT

This control type corresponds to HTTP elements identified by <input type=submit> tags.

Service Request Options:

Example:

    HTML : 
      <input type=submit name=button_1 value=do_1/>
    Service : 
      SET FORM form_1 CONTROLNAME submit VALUE button_1=do_1
    HTTP : 
      button_1=do

Notes:

  1. Only one SUBMIT or IMAGE control element may be selected at a time.
  2. The value name is restricted to controls which exist in the form when it is acquired.

INPUT type IMAGE

This control type corresponds to HTTP elements identified by <input type=img> tags.

Service Request Options:

Example:

    HTML : 
      <input type=img name=picture_1 src="./images/pic.jpg" valueX=123 valueY=80/>
    Service : 
      SET FORM form_1 CONTROLNAME submit VALUE picture_1=,123,80
    HTTP : 
      picture_1.x=123&picture_1.y=80

Notes:

  1. The value name is restricted to controls which exist in the form when it is acquired.
  2. Only one SUBMIT or IMAGE control element may be selected at a time.
  3. If the initial selection of the form submission control is of type IMAGE, the coordinates are set to <valueX>,<valueY> by default.
  4. The HTTP service does not check if the input coordinates are valid.

INPUT other types

This control type corresponds to HTTP elements identified by <input> tags with other type attributes (e.g. text, file, hidden, password)

Service Request Options:

Example:

    HTML : 
      <input type=text name=text_1 value="some text" />
      <input type=file name=file_1 value="c:\temp.gif" />
      <input type=hidden name=hidden_1 value=secret />
      <input type=password name=pwd_1 value=pwd />
    Service : 
      SET FORM form_1 CONTROLNAME text_1 VALUE "some text"
      SET FORM form_1 CONTROLNAME file_1 VALUE "c:\temp.gif"
      SET FORM form_1 CONTROLNAME hidden_1 VALUE secret
      SET FORM form_1 CONTROLNAME pwd_1 VALUE !!@pwd@!!
    HTTP : 
      text_1=some+text&hidden_1=secret&pwd_1=pwd
This ignores the file since that causes a multipart post which has a different format.

Notes:

  1. A bad value for an INPUT of type FILE will cause form submission to fail.
  2. The presence of an INPUT of type FILE will cause a multipart post which has a different HTTP format than the example.

An explanation of multipart/form-data can be found in the Processing form data section in hte W3C HTML Specification.

SELECT

This control type corresponds to HTTP elements identified by <select> tags.

Service Request Options:

Example:

    HTML : 
      <select name=select_1 multiple/>
        <option value=o_1>1</option>
        <option value=o_2 selected>2</option>
        <option value=o_3 selected>3</option>
      <select/>
    Service : 
      SET FORM form_1 CONTROLNAME select_1 VALUE o_2
      SET FORM form_1 CONTROLNAME select_1 VALUE o_3
    HTTP : 
      select_1=o_2&select_1=o_3

Note: It is necessary to explicitly de-select elements. This is true with and without the multiple option in the html <select> tag. If the element is a single select, attempting to select a new option before de-selecting the current option will result in an Invalid Value Error.

Appendix B: SSL

The HTTP service uses HttpClient allows for navigation of ssl sites through the use of JSSE which is bundled with J2SE 1.4 and later.

Https is the protocol recognized by HttpClient for SSL. See the HttpClient SSL guide for more information.

Invalid JSSE configuration can be recognized by an RC 4000 when accessing a secure site with a java.lang.NoClassDefFoundError: javax/net/ssl/SSLSocketFactory message.

Notes:

  1. When authenticating with cookies, if you are having trouble logging into a secure site and are not getting error messages on the post, try setting your cookie policy to COMPATIBILITY. It may be that the site you are attempting to log into does not use rc2109 compliant cookies, and you are not setting a needed cookie.

  2. When authenticating with cookies, if you are having trouble logging into a secure site and are receiving a http status code of 3XX on the post, it may be that additional cookies are being set by the page you are being redirected through. Try using the FOLLOWREDIRECT option with the post request.

  3. When submitting a preemptive authentication management request (e.g. specifying a request using the AUTHENTICATIONHOST option), if you are having trouble with authentication denied (401), check the JVMLog to get more detailed realm and host error information.

Examples

Goal: Login to the SourceForge website and go to the user's homepage. This is an example that uses cookies to authenticate. Use privacy delimiters to protect the password.

DOPOST URL http://sourceforge.net/account/login.php PARAMETER form_loginname=user PARAMETER form_pw=!!@password@!! PARAMETER login=Login+With+SSL SESSION 1 RETURNNOCONTENT RETURNHEADERS

DOGET URL https://sourceforge.net/my SESSION 1

Goal: Login to a private site that issues an authentication challenge that must be answered though user/password pop-up prompt. This is an example that uses preemptive authentication. Use privacy delimiters to protect the password.

SET AUTHENTICATIONHOST www.theSite.com AUTHENTICATIONUSER user AUTHENTICATIONPASSWORD !!@pwd@!!

DOGET URL www.theSite.com/myPersonalSection/index.html

Appendix C: Licenses and Acknowledgements

Apache Code Notices and Information

STAF's HTTP Service includes all or portions of the following software which IBM obtained under the terms and conditions of the Apache License Version 2.0, January 2004. This software may also consist of voluntary contributions made by many individuals to the Apache Software Foundation. For more information on the Apache Software Foundation, please see http://www.apache.org.

Acknowledgement

This product includes software developed by the Apache Software Foundation (http://www.apache.org/").

Apache License

IBM is required to provide you, as the recipient of such software, with a copy of the following license notice from the Apache Software Foundation:

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION

   1. Definitions.

      "License" shall mean the terms and conditions for use, reproduction,
      and distribution as defined by Sections 1 through 9 of this document.

      "Licensor" shall mean the copyright owner or entity authorized by
      the copyright owner that is granting the License.

      "Legal Entity" shall mean the union of the acting entity and all
      other entities that control, are controlled by, or are under common
      control with that entity. For the purposes of this definition,
      "control" means (i) the power, direct or indirect, to cause the
      direction or management of such entity, whether by contract or
      otherwise, or (ii) ownership of fifty percent (50%) or more of the
      outstanding shares, or (iii) beneficial ownership of such entity.

      "You" (or "Your") shall mean an individual or Legal Entity
      exercising permissions granted by this License.

      "Source" form shall mean the preferred form for making modifications,
      including but not limited to software source code, documentation
      source, and configuration files.

      "Object" form shall mean any form resulting from mechanical
      transformation or translation of a Source form, including but
      not limited to compiled object code, generated documentation,
      and conversions to other media types.

      "Work" shall mean the work of authorship, whether in Source or
      Object form, made available under the License, as indicated by a
      copyright notice that is included in or attached to the work
      (an example is provided in the Appendix below).

      "Derivative Works" shall mean any work, whether in Source or Object
      form, that is based on (or derived from) the Work and for which the
      editorial revisions, annotations, elaborations, or other modifications
      represent, as a whole, an original work of authorship. For the purposes
      of this License, Derivative Works shall not include works that remain
      separable from, or merely link (or bind by name) to the interfaces of,
      the Work and Derivative Works thereof.

      "Contribution" shall mean any work of authorship, including
      the original version of the Work and any modifications or additions
      to that Work or Derivative Works thereof, that is intentionally
      submitted to Licensor for inclusion in the Work by the copyright owner
      or by an individual or Legal Entity authorized to submit on behalf of
      the copyright owner. For the purposes of this definition, "submitted"
      means any form of electronic, verbal, or written communication sent
      to the Licensor or its representatives, including but not limited to
      communication on electronic mailing lists, source code control systems,
      and issue tracking systems that are managed by, or on behalf of, the
      Licensor for the purpose of discussing and improving the Work, but
      excluding communication that is conspicuously marked or otherwise
      designated in writing by the copyright owner as "Not a Contribution."

      "Contributor" shall mean Licensor and any individual or Legal Entity
      on behalf of whom a Contribution has been received by Licensor and
      subsequently incorporated within the Work.

   2. Grant of Copyright License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      copyright license to reproduce, prepare Derivative Works of,
      publicly display, publicly perform, sublicense, and distribute the
      Work and such Derivative Works in Source or Object form.

   3. Grant of Patent License. Subject to the terms and conditions of
      this License, each Contributor hereby grants to You a perpetual,
      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
      (except as stated in this section) patent license to make, have made,
      use, offer to sell, sell, import, and otherwise transfer the Work,
      where such license applies only to those patent claims licensable
      by such Contributor that are necessarily infringed by their
      Contribution(s) alone or by combination of their Contribution(s)
      with the Work to which such Contribution(s) was submitted. If You
      institute patent litigation against any entity (including a
      cross-claim or counterclaim in a lawsuit) alleging that the Work
      or a Contribution incorporated within the Work constitutes direct
      or contributory patent infringement, then any patent licenses
      granted to You under this License for that Work shall terminate
      as of the date such litigation is filed.

   4. Redistribution. You may reproduce and distribute copies of the
      Work or Derivative Works thereof in any medium, with or without
      modifications, and in Source or Object form, provided that You
      meet the following conditions:

      (a) You must give any other recipients of the Work or
          Derivative Works a copy of this License; and

      (b) You must cause any modified files to carry prominent notices
          stating that You changed the files; and

      (c) You must retain, in the Source form of any Derivative Works
          that You distribute, all copyright, patent, trademark, and
          attribution notices from the Source form of the Work,
          excluding those notices that do not pertain to any part of
          the Derivative Works; and

      (d) If the Work includes a "NOTICE" text file as part of its
          distribution, then any Derivative Works that You distribute must
          include a readable copy of the attribution notices contained
          within such NOTICE file, excluding those notices that do not
          pertain to any part of the Derivative Works, in at least one
          of the following places: within a NOTICE text file distributed
          as part of the Derivative Works; within the Source form or
          documentation, if provided along with the Derivative Works; or,
          within a display generated by the Derivative Works, if and
          wherever such third-party notices normally appear. The contents
          of the NOTICE file are for informational purposes only and
          do not modify the License. You may add Your own attribution
          notices within Derivative Works that You distribute, alongside
          or as an addendum to the NOTICE text from the Work, provided
          that such additional attribution notices cannot be construed
          as modifying the License.

      You may add Your own copyright statement to Your modifications and
      may provide additional or different license terms and conditions
      for use, reproduction, or distribution of Your modifications, or
      for any such Derivative Works as a whole, provided Your use,
      reproduction, and distribution of the Work otherwise complies with
      the conditions stated in this License.

   5. Submission of Contributions. Unless You explicitly state otherwise,
      any Contribution intentionally submitted for inclusion in the Work
      by You to the Licensor shall be under the terms and conditions of
      this License, without any additional terms or conditions.
      Notwithstanding the above, nothing herein shall supersede or modify
      the terms of any separate license agreement you may have executed
      with Licensor regarding such Contributions.

   6. Trademarks. This License does not grant permission to use the trade
      names, trademarks, service marks, or product names of the Licensor,
      except as required for reasonable and customary use in describing the
      origin of the Work and reproducing the content of the NOTICE file.

   7. Disclaimer of Warranty. Unless required by applicable law or
      agreed to in writing, Licensor provides the Work (and each
      Contributor provides its Contributions) on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
      implied, including, without limitation, any warranties or conditions
      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
      PARTICULAR PURPOSE. You are solely responsible for determining the
      appropriateness of using or redistributing the Work and assume any
      risks associated with Your exercise of permissions under this License.

   8. Limitation of Liability. In no event and under no legal theory,
      whether in tort (including negligence), contract, or otherwise,
      unless required by applicable law (such as deliberate and grossly
      negligent acts) or agreed to in writing, shall any Contributor be
      liable to You for damages, including any direct, indirect, special,
      incidental, or consequential damages of any character arising as a
      result of this License or out of the use or inability to use the
      Work (including but not limited to damages for loss of goodwill,
      work stoppage, computer failure or malfunction, or any and all
      other commercial damages or losses), even if such Contributor
      has been advised of the possibility of such damages.

   9. Accepting Warranty or Additional Liability. While redistributing
      the Work or Derivative Works thereof, You may choose to offer,
      and charge a fee for, acceptance of support, warranty, indemnity,
      or other liability obligations and/or rights consistent with this
      License. However, in accepting such obligations, You may act only
      on Your own behalf and on Your sole responsibility, not on behalf
      of any other Contributor, and only if You agree to indemnify,
      defend, and hold each Contributor harmless for any liability
      incurred by, or claims asserted against, such Contributor by reason
      of your accepting any such warranty or additional liability.

   END OF TERMS AND CONDITIONS

NekoHTML Notices and Information

STAF's HTTP Service includes all or portions of CyberNeko HTML Parser 0.9.5 (NekoHTML) which IBM obtained under the terms and conditions of the CyberNeko Software License Version 1.0 (BSD Style), Apache License Version 1.1, Apache License 2.0 (shown above), and W3C Document Notice and License. For more information on NekoHtml, please see http://sourceforge.net/projects/nekohtml.

NekoHTML is a simple HTML scanner and tag balancer that enables application programmers to parse HTML documents and access the information using standard XML interfaces.

Acknowledgement

This product includes software developed by Andy Clark.

NekoHTML Licenses

The CyberNeko Software License. Version 1.0  (BSD Style)
--------------------------------------------------------

(C) Copyright 2002-2005, Andy Clark.  All rights reserved.
 
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer. 

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in
   the documentation and/or other materials provided with the
   distribution.

3. The end-user documentation included with the redistribution,
   if any, must include the following acknowledgment:  
     "This product includes software developed by Andy Clark."
   Alternately, this acknowledgment may appear in the software itself,
   if and wherever such third-party acknowledgments normally appear.

4. The names "CyberNeko" and "NekoHTML" must not be used to endorse
   or promote products derived from this software without prior 
   written permission. For written permission, please contact 
   andyc@cyberneko.net.

5. Products derived from this software may not be called "CyberNeko",
   nor may "CyberNeko" appear in their name, without prior written
   permission of the author.

THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR OTHER CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 
OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 
OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

====================================================================

This license is based on the Apache Software License, version 1.1.


W3C DOCUMENT NOTICE AND LICENSE
--------------------------------
http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231:

Copyright © 1994-2002 World Wide Web Consortium, (Massachusetts Institute
of Technology, Institut National de Recherche en Informatique et en
Automatique, Keio University). All Rights Reserved.
http://www.w3.org/Consortium/Legal/

Public documents on the W3C site are provided by the copyright holders
under the following license. The software or Document Type Definitions
(DTDs) associated with W3C specifications are governed by the Software
Notice. By using and/or copying this document, or the W3C document from
which this statement is linked, you (the licensee) agree that you have
read, understood, and will comply with the following terms and conditions:

Permission to use, copy, and distribute the contents of this document, or
the W3C document from which this statement is linked, in any medium for
any purpose and without fee or royalty is hereby granted, provided that
you include the following on ALL copies of the document, or portions
thereof, that you use:

   1. A link or URL to the original W3C document.
   2. The pre-existing copyright notice of the original author, or if it
      doesn't exist, a notice of the form: "Copyright © [$date-of-document]
      World Wide Web Consortium, (Massachusetts Institute of Technology,
      Institut National de Recherche en Informatique et en Automatique,
      Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/"
      (Hypertext is preferred, but a textual representation is permitted.)
   3. If it exists, the STATUS of the W3C document.

When space permits, inclusion of the full text of this NOTICE should be
provided. We request that authorship attribution be provided in any software,
documents, or other items or products that you create pursuant to the
implementation of the contents of this document, or any portion thereof.

No right to create modifications or derivatives of W3C documents is granted
pursuant to this license. However, if additional requirements (documented in
the Copyright FAQ) are satisfied, the right to create modifications or
derivatives is sometimes granted by the W3C to individuals complying with
those requirements.

THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO
REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT
LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE
FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT
INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE
PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.

The name and trademarks of copyright holders may NOT be used in advertising
or publicity pertaining to this document or its contents without specific,
written prior permission. Title to copyright in this document will at all
times remain with copyright holders.

----------------------------------------------------------------------------

This formulation of W3C's notice and license became active on April 05 1999
so as to account for the treatment of DTDs, schema's and bindings. See the
older formulation for the policy prior to this date. Please see our Copyright
FAQ for common questions about using materials from our site, including
specific terms and conditions for packages like libwww, Amaya, and Jigsaw.
Other questions about this notice can be directed to site-policy@w3.org.
webmaster
(last updated by reagle on 1999/04/99.)

Xerces2-J Notices and Information

STAF's HTTP Service includes all or portions of Xerces2-J 2.6.2 which IBM obtained under the terms and conditions of the Apache License Version 1.1. This software may also consist of voluntary contributions made by many individuals to the Apache Software Foundation. For more information on the Apache Software Foundation, please see http://www.apache.org.

XML Parser for Java (Xerces2-J) is a validating XML parser and processor written in 100% pure Java; it is a library for parsing and generating XML documents. This parser easily enables an application to read and write XML data.

Acknowledgement

This product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Apache License Version 1.1

/*
 * The Apache Software License, Version 1.1
 *
 *
 * Copyright (c) 1999-2004 The Apache Software Foundation.  All rights 
 * reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer. 
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. The end-user documentation included with the redistribution,
 *    if any, must include the following acknowledgment:  
 *       "This product includes software developed by the
 *        Apache Software Foundation (http://www.apache.org/)."
 *    Alternately, this acknowledgment may appear in the software itself,
 *    if and wherever such third-party acknowledgments normally appear.
 *
 * 4. The names "Xerces" and "Apache Software Foundation" must
 *    not be used to endorse or promote products derived from this
 *    software without prior written permission. For written 
 *    permission, please contact apache@apache.org.
 *
 * 5. Products derived from this software may not be called "Apache",
 *    nor may "Apache" appear in their name, without prior written
 *    permission of the Apache Software Foundation.
 *
 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 * ====================================================================
 *
 * This software consists of voluntary contributions made by many
 * individuals on behalf of the Apache Software Foundation and was
 * originally based on software copyright (c) 1999, International
 * Business Machines, Inc., http://www.ibm.com.  For more
 * information on the Apache Software Foundation, please see
 * <http://www.apache.org/>.
 */