IP*Works!

ipworks
Class Http

java.lang.Object
  |
  +--ipworks.Http

public class Http
extends java.lang.Object

The HTTP class can be used to retrieve documents from the World Wide Web.

The HTTP class implements a standard HTTP client through a simple plug-and-play interface.

The class contains a number of properties that map directly to HTTP request headers. Files are received through events: Transfer for contents, and Header for HTTP headers. The StartTransfer and EndTransfer events are fired at the beginning and end of transmission.

The URL property specifies the document to receive. To receive the document set the Action property to 'Get'. Data can be POST-ed to the HTTP server by assigning it to the PostData property and then setting the Action property to 'Post'.

The PUT method is also supported: the user should set the URL , User and Password or alternatively Authorization and set Action to 'Put'. The AttachedFile will be sent.

The HTTP class supports the HTTP Basic authentication scheme through the User and Password properties. Other authentication schemes can be implemented by using the Authorization property.


Field Summary
static int a_Get
           
static int a_Head
           
static int a_Idle
           
static int a_Post
           
static int a_Put
           
static int a_ResetHeaders
           
 
Constructor Summary
Http()
           
 
Method Summary
 void addHttpEventListener(HttpEventListener l)
           
 void fireConnected(int statusCode, java.lang.String description)
          Fired immediately after a connection completes (or fails).
 void fireDisconnected(int statusCode, java.lang.String description)
          Fired when a connection is closed.
 void fireEndTransfer(int direction)
          Fired when a document finishes transferring.
 void fireError(int errorCode, java.lang.String description)
          Information about errors during data delivery.
 void fireHeader(java.lang.String field, java.lang.String value)
          Fired every time a header line comes in.
 void fireStartTransfer(int direction)
          Fired when a document starts transferring (after the headers).
 void fireTransfer(int direction, int bytesTransferred, byte[] text)
          Fired while a document transfers (delivers document).
 java.lang.String getAccept()
          A list of acceptable MIME types for the request.
 int getAction()
          An action code for the component.
 java.lang.String getAttachedFile()
          A file to append to PostData if the POST or PUT methods are used.
 java.lang.String getAuthorization()
          The Authorization string to be sent to the server.
 java.lang.String getContentType()
          Content type for posted data.
 java.lang.String getFrom()
          The email address of the HTTP agent (optional).
 java.lang.String getHTTPVersion()
          The version of HTTP used (default is HTTP/1.0).
 java.lang.String getIfModifiedSince()
          A date determining the maximum age of the desired document.
 java.lang.String getLocalFile()
          The path to a local file for downloading.
 java.lang.String getLocalHost()
          The name of the local host.
 java.lang.String getOtherHeaders()
          Other headers as determined by the user (optional).
 java.lang.String getPassword()
          A password if Basic authentication is to be used.
 byte[] getPostData()
          The data to post with the URL if the POST method is used.
 java.lang.String getPragma()
          A browser/server specific header line (optional).
 int getProxyPort()
          Port for the proxy server (default 80).
 java.lang.String getProxyServer()
          Name or IP address of a proxy server (optional).
 java.lang.String getReferer()
          Referer URL/document (optional).
 java.lang.String getStatusLine()
          The first line of the last server response.
 java.lang.String getURL()
          The URL to fetch.
 java.lang.String getURLPath()
          The path for the URL.
 int getURLPort()
          The port for the URL.
 java.lang.String getURLScheme()
          The scheme for the URL.
 java.lang.String getURLServer()
          The server for the URL.
 java.lang.String getUser()
          A user name if Basic authentication is to be used.
 java.lang.String getUserAgent()
          Information about the user agent (browser).
 void removeHttpEventListener(HttpEventListener l)
           
 void setAccept(java.lang.String accept)
          A list of acceptable MIME types for the request.
 void setAction(int action)
          An action code for the component.
 void setAttachedFile(java.lang.String attachedFile)
          A file to append to PostData if the POST or PUT methods are used.
 void setAuthorization(java.lang.String authorization)
          The Authorization string to be sent to the server.
 void setContentType(java.lang.String contentType)
          Content type for posted data.
 void setFrom(java.lang.String from)
          The email address of the HTTP agent (optional).
 void setHTTPVersion(java.lang.String HTTPVersion)
          The version of HTTP used (default is HTTP/1.0).
 void setIfModifiedSince(java.lang.String ifModifiedSince)
          A date determining the maximum age of the desired document.
 void setLocalFile(java.lang.String localFile)
          The path to a local file for downloading.
 void setOtherHeaders(java.lang.String otherHeaders)
          Other headers as determined by the user (optional).
 void setPassword(java.lang.String password)
          A password if Basic authentication is to be used.
 void setPostData(byte[] postData)
          The data to post with the URL if the POST method is used.
 void setPragma(java.lang.String pragma)
          A browser/server specific header line (optional).
 void setProxyPort(int proxyPort)
          Port for the proxy server (default 80).
 void setProxyServer(java.lang.String proxyServer)
          Name or IP address of a proxy server (optional).
 void setReferer(java.lang.String referer)
          Referer URL/document (optional).
 void setURL(java.lang.String URL)
          The URL to fetch.
 void setURLPath(java.lang.String URLPath)
          The path for the URL.
 void setURLPort(int URLPort)
          The port for the URL.
 void setURLScheme(java.lang.String URLScheme)
          The scheme for the URL.
 void setURLServer(java.lang.String URLServer)
          The server for the URL.
 void setUser(java.lang.String user)
          A user name if Basic authentication is to be used.
 void setUserAgent(java.lang.String userAgent)
          Information about the user agent (browser).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

a_Idle

public static final int a_Idle

a_Get

public static final int a_Get

a_Post

public static final int a_Post

a_Head

public static final int a_Head

a_ResetHeaders

public static final int a_ResetHeaders

a_Put

public static final int a_Put
Constructor Detail

Http

public Http()
Method Detail

getAccept

public java.lang.String getAccept()
A list of acceptable MIME types for the request. If the Accept property contains a non-empty string, an HTTP Accept header is added to the request.

The Accept header is used for content negotiation. It consists of a comma-separated list of acceptable MIME types.


setAccept

public void setAccept(java.lang.String accept)
               throws IPWorksException
A list of acceptable MIME types for the request. If the Accept property contains a non-empty string, an HTTP Accept header is added to the request.

The Accept header is used for content negotiation. It consists of a comma-separated list of acceptable MIME types.


getAction

public int getAction()
An action code for the component. Setting the Action property to a valid action code makes the class perform the associated action. If the action completes successfully, execution continues normally, and Action is reset to 0 (Idle). If an error happens, then an IPWorksException exception is raised.

The following are the possible values for the Action property and the corresponding descriptions:

a_Idle
Default action. It can also be used to interrupt the current operation.
a_Get
Fetch the document using the HTTP GET method. The document contents are delivered through the Transfer event, and the HTTP response headers through the Header event. If LocalFile is not empty the data (not the headers) is written there as well.
a_Post
Post data to the HTTP server using the HTTP POST method. The posted data are taken from PostData and/or AttachedFile . The server response text is received through the Transfer event, and the HTTP response headers through the Header event. If LocalFile is not empty the data (not the headers) is written there as well.
a_Head
Fetch the document headers using the HTTP HEAD method. The headers are received through the Header event.
a_ResetHeaders
Resets all the HTTP headers as well as LocalFile and AttachedFile to "" (empty string). Use this property before creating a new request, so that headers from the previous message are not carried over to the next one.
a_Put
Send data to the HTTP server using the HTTP PUT method. The data are taken from PostData and/or AttachedFile . The server response text is received through the Transfer event, and the HTTP response headers through the Header event. If LocalFile is not empty the data (not the headers) is written there as well. The user should normally have assigned correct values to User and Password or Authorization .


setAction

public void setAction(int action)
               throws IPWorksException
An action code for the component. Setting the Action property to a valid action code makes the class perform the associated action. If the action completes successfully, execution continues normally, and Action is reset to 0 (Idle). If an error happens, then an IPWorksException exception is raised.

The following are the possible values for the Action property and the corresponding descriptions:

a_Idle
Default action. It can also be used to interrupt the current operation.
a_Get
Fetch the document using the HTTP GET method. The document contents are delivered through the Transfer event, and the HTTP response headers through the Header event. If LocalFile is not empty the data (not the headers) is written there as well.
a_Post
Post data to the HTTP server using the HTTP POST method. The posted data are taken from PostData and/or AttachedFile . The server response text is received through the Transfer event, and the HTTP response headers through the Header event. If LocalFile is not empty the data (not the headers) is written there as well.
a_Head
Fetch the document headers using the HTTP HEAD method. The headers are received through the Header event.
a_ResetHeaders
Resets all the HTTP headers as well as LocalFile and AttachedFile to "" (empty string). Use this property before creating a new request, so that headers from the previous message are not carried over to the next one.
a_Put
Send data to the HTTP server using the HTTP PUT method. The data are taken from PostData and/or AttachedFile . The server response text is received through the Transfer event, and the HTTP response headers through the Header event. If LocalFile is not empty the data (not the headers) is written there as well. The user should normally have assigned correct values to User and Password or Authorization .


getAttachedFile

public java.lang.String getAttachedFile()
A file to append to PostData if the POST or PUT methods are used. If AttachedFile is a non-empty string, then if the HTTP 'POST' or 'PUT' methods are used ( Post Data or Put Data Action ), the contents of the AttachedFile file are appended to the HTTP request after any data in PostData .

An HTTP 'Content-Length' header is also added to request. Its value is the cumulative length of the PostData string and the file.


setAttachedFile

public void setAttachedFile(java.lang.String attachedFile)
                     throws IPWorksException
A file to append to PostData if the POST or PUT methods are used. If AttachedFile is a non-empty string, then if the HTTP 'POST' or 'PUT' methods are used ( Post Data or Put Data Action ), the contents of the AttachedFile file are appended to the HTTP request after any data in PostData .

An HTTP 'Content-Length' header is also added to request. Its value is the cumulative length of the PostData string and the file.


getAuthorization

public java.lang.String getAuthorization()
The Authorization string to be sent to the server. If the Authorization property contains a non-empty string, an Authorization HTTP request header is added to the request. This header conveys Authorization information to the server.

This property is provided so that the HTTP class can be extended with other security schemes except the common Basic authorization scheme defined by the HTTP protocol.

If User and Password are specified, they are Base64 encoded, and the result is put in the Authorization property in the form "Basic [encoded-user-password]".


setAuthorization

public void setAuthorization(java.lang.String authorization)
                      throws IPWorksException
The Authorization string to be sent to the server. If the Authorization property contains a non-empty string, an Authorization HTTP request header is added to the request. This header conveys Authorization information to the server.

This property is provided so that the HTTP class can be extended with other security schemes except the common Basic authorization scheme defined by the HTTP protocol.

If User and Password are specified, they are Base64 encoded, and the result is put in the Authorization property in the form "Basic [encoded-user-password]".


getContentType

public java.lang.String getContentType()
Content type for posted data. If the ContentType property contains a non-empty string, a Content-Type HTTP request header is added to the request. The purpose of the header is to show the contents of the data being POST-ed to the server.

The most common example is posting of HTML form input data. In that case, the ContentType property must be set to "application/x-www-form-urlencoded" .


setContentType

public void setContentType(java.lang.String contentType)
                    throws IPWorksException
Content type for posted data. If the ContentType property contains a non-empty string, a Content-Type HTTP request header is added to the request. The purpose of the header is to show the contents of the data being POST-ed to the server.

The most common example is posting of HTML form input data. In that case, the ContentType property must be set to "application/x-www-form-urlencoded" .


getFrom

public java.lang.String getFrom()
The email address of the HTTP agent (optional). If the From property contains a non-empty string, an HTTP From: header is added to the request. This header generally gives the email address of the requester of the document.


setFrom

public void setFrom(java.lang.String from)
             throws IPWorksException
The email address of the HTTP agent (optional). If the From property contains a non-empty string, an HTTP From: header is added to the request. This header generally gives the email address of the requester of the document.


getHTTPVersion

public java.lang.String getHTTPVersion()
The version of HTTP used (default is HTTP/1.0). None.


setHTTPVersion

public void setHTTPVersion(java.lang.String HTTPVersion)
                    throws IPWorksException
The version of HTTP used (default is HTTP/1.0). None.


getIfModifiedSince

public java.lang.String getIfModifiedSince()
A date determining the maximum age of the desired document. If the IfModifiedSince property contains a non-empty string, a If-Modified-Since HTTP request header is added to the request. The value of the header is used to make the HTTP request conditional: if the requested documented has not been modified since the time specified in the field, a copy of the document will not be returned from the server; instead, a 304 (not modified) response will be returned only.

The format of the date value for IfModifiedSince is detailed in the HTTP specs. An example is Sat, 29 Oct 1994 19:43:31 GMT.


setIfModifiedSince

public void setIfModifiedSince(java.lang.String ifModifiedSince)
                        throws IPWorksException
A date determining the maximum age of the desired document. If the IfModifiedSince property contains a non-empty string, a If-Modified-Since HTTP request header is added to the request. The value of the header is used to make the HTTP request conditional: if the requested documented has not been modified since the time specified in the field, a copy of the document will not be returned from the server; instead, a 304 (not modified) response will be returned only.

The format of the date value for IfModifiedSince is detailed in the HTTP specs. An example is Sat, 29 Oct 1994 19:43:31 GMT.


getLocalHost

public java.lang.String getLocalHost()
The name of the local host. When connected, the IP address of the interface through which the connection was made. The LocalHost property contains the name of the local host as obtained by the gethostname() Winsock call.

If the class is connected, the LocalHost property shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).


getLocalFile

public java.lang.String getLocalFile()
The path to a local file for downloading. If the file exists, it is overwritten. (optional) The LocalFile property is used when getting a document via the Action property. If LocalFile is empty then the received data is provided through the parameters of the Transfer event.


setLocalFile

public void setLocalFile(java.lang.String localFile)
                  throws IPWorksException
The path to a local file for downloading. If the file exists, it is overwritten. (optional) The LocalFile property is used when getting a document via the Action property. If LocalFile is empty then the received data is provided through the parameters of the Transfer event.


getOtherHeaders

public java.lang.String getOtherHeaders()
Other headers as determined by the user (optional). The OtherHeaders property contains a string of headers to be appended to the HTTP request headers created from other properties like ContentType , From , etc.

The headers must of the format "header: value" as specified in the HTTP specs. Header lines should be separated by CRLF ("\\r\\n").

Use this property with caution. If OtherHeaders contains invalid headers, HTTP requests may fail.

The OtherHeaders property is useful for extending the functionality of the class beyond what is provided.


setOtherHeaders

public void setOtherHeaders(java.lang.String otherHeaders)
                     throws IPWorksException
Other headers as determined by the user (optional). The OtherHeaders property contains a string of headers to be appended to the HTTP request headers created from other properties like ContentType , From , etc.

The headers must of the format "header: value" as specified in the HTTP specs. Header lines should be separated by CRLF ("\\r\\n").

Use this property with caution. If OtherHeaders contains invalid headers, HTTP requests may fail.

The OtherHeaders property is useful for extending the functionality of the class beyond what is provided.


getPassword

public java.lang.String getPassword()
A password if Basic authentication is to be used. The User and Password are Base64 encoded and the result is put in the Authorization property in the form "Basic [encoded-user-password]".

The User and Password properties must be set only after the URL property is set. When the URL property is set, for security reasons, the User and Password properties are immediately cleared.


setPassword

public void setPassword(java.lang.String password)
                 throws IPWorksException
A password if Basic authentication is to be used. The User and Password are Base64 encoded and the result is put in the Authorization property in the form "Basic [encoded-user-password]".

The User and Password properties must be set only after the URL property is set. When the URL property is set, for security reasons, the User and Password properties are immediately cleared.


getPostData

public byte[] getPostData()
The data to post with the URL if the POST method is used. If PostData is a non-empty string, then if the HTTP 'POST' method is used ( Post Data Action ), the contents of the PostData property are appended to the HTTP request after the HTTP headers.

An HTTP 'Content-Length' header is also added to the request. Its value is the length of the string in PostData , or, if the AttachedFile property has been set, the cumulative length of the string and the file. See the description of the AttachedFile property for details.


setPostData

public void setPostData(byte[] postData)
                 throws IPWorksException
The data to post with the URL if the POST method is used. If PostData is a non-empty string, then if the HTTP 'POST' method is used ( Post Data Action ), the contents of the PostData property are appended to the HTTP request after the HTTP headers.

An HTTP 'Content-Length' header is also added to the request. Its value is the length of the string in PostData , or, if the AttachedFile property has been set, the cumulative length of the string and the file. See the description of the AttachedFile property for details.


getPragma

public java.lang.String getPragma()
A browser/server specific header line (optional). If the Pragma property contains a non-empty string, a Pragma HTTP request header is added to the request. The meaning of the header depends on the implementation and can be used to send/receive proprietary information to/from the server.


setPragma

public void setPragma(java.lang.String pragma)
               throws IPWorksException
A browser/server specific header line (optional). If the Pragma property contains a non-empty string, a Pragma HTTP request header is added to the request. The meaning of the header depends on the implementation and can be used to send/receive proprietary information to/from the server.


getProxyPort

public int getProxyPort()
Port for the proxy server (default 80). The TCP port for the ProxyServer . See the description of the ProxyServer property for details.


setProxyPort

public void setProxyPort(int proxyPort)
                  throws IPWorksException
Port for the proxy server (default 80). The TCP port for the ProxyServer . See the description of the ProxyServer property for details.


getProxyServer

public java.lang.String getProxyServer()
Name or IP address of a proxy server (optional). If a ProxyServer is given, then the HTTP request is sent to the proxy instead of the server specified in the URL .

If the ProxyServer property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the ProxyServer property is set to the corresponding address. If the search is not successful, an error is returned.


setProxyServer

public void setProxyServer(java.lang.String proxyServer)
                    throws IPWorksException
Name or IP address of a proxy server (optional). If a ProxyServer is given, then the HTTP request is sent to the proxy instead of the server specified in the URL .

If the ProxyServer property is set to a Domain Name, a DNS request is initiated and upon successful termination of the request, the ProxyServer property is set to the corresponding address. If the search is not successful, an error is returned.


getReferer

public java.lang.String getReferer()
Referer URL/document (optional). If the Referer property contains a non-empty string, a Referer HTTP request header is added to the request. The purpose of the header is to show the document referring the requested URL.


setReferer

public void setReferer(java.lang.String referer)
                throws IPWorksException
Referer URL/document (optional). If the Referer property contains a non-empty string, a Referer HTTP request header is added to the request. The purpose of the header is to show the document referring the requested URL.


getStatusLine

public java.lang.String getStatusLine()
The first line of the last server response. This value can be used for diagnostic purposes. If an HTTP error is returned when setting the Action property, the error string is the same as the StatusLine property.

The HTTP protocol specifies the structure of the StatusLine as: [HTTP version] [Result Code] [Description].


getURL

public java.lang.String getURL()
The URL to fetch. The URL of the document. This value is parsed, and the results are put in the URLScheme , URLServer , URLPort , and URLPath properties.


setURL

public void setURL(java.lang.String URL)
            throws IPWorksException
The URL to fetch. The URL of the document. This value is parsed, and the results are put in the URLScheme , URLServer , URLPort , and URLPath properties.


getURLPath

public java.lang.String getURLPath()
The path for the URL. The URL path as determined by parsing the value set in the URL property.


setURLPath

public void setURLPath(java.lang.String URLPath)
                throws IPWorksException
The path for the URL. The URL path as determined by parsing the value set in the URL property.


getURLPort

public int getURLPort()
The port for the URL. The HTTP server port as determined by parsing the value set in the URL property.


setURLPort

public void setURLPort(int URLPort)
                throws IPWorksException
The port for the URL. The HTTP server port as determined by parsing the value set in the URL property.


getURLScheme

public java.lang.String getURLScheme()
The scheme for the URL. The URL scheme as determined by parsing the value set in the URL property.


setURLScheme

public void setURLScheme(java.lang.String URLScheme)
                  throws IPWorksException
The scheme for the URL. The URL scheme as determined by parsing the value set in the URL property.


getURLServer

public java.lang.String getURLServer()
The server for the URL. The HTTP server name as determined by parsing the value set in the URL property.


setURLServer

public void setURLServer(java.lang.String URLServer)
                  throws IPWorksException
The server for the URL. The HTTP server name as determined by parsing the value set in the URL property.


getUser

public java.lang.String getUser()
A user name if Basic authentication is to be used. The User and Password are Base64 encoded, and the result is put in the Authorization property in the form "Basic [encoded-user-password]".

The User and Password properties must be set only after the URL property is set. When the URL property is set, for security reasons, the User and Password properties are immediately cleared.


setUser

public void setUser(java.lang.String user)
             throws IPWorksException
A user name if Basic authentication is to be used. The User and Password are Base64 encoded, and the result is put in the Authorization property in the form "Basic [encoded-user-password]".

The User and Password properties must be set only after the URL property is set. When the URL property is set, for security reasons, the User and Password properties are immediately cleared.


getUserAgent

public java.lang.String getUserAgent()
Information about the user agent (browser). Override the default with the name and version of your software.


setUserAgent

public void setUserAgent(java.lang.String userAgent)
                  throws IPWorksException
Information about the user agent (browser). Override the default with the name and version of your software.


fireConnected

public void fireConnected(int statusCode,
                          java.lang.String description)
Fired immediately after a connection completes (or fails). (Called internally to dispatch the event.)
See Also:
HttpConnectedEvent

fireDisconnected

public void fireDisconnected(int statusCode,
                             java.lang.String description)
Fired when a connection is closed. (Called internally to dispatch the event.)
See Also:
HttpDisconnectedEvent

fireEndTransfer

public void fireEndTransfer(int direction)
Fired when a document finishes transferring. (Called internally to dispatch the event.)
See Also:
HttpEndTransferEvent

fireError

public void fireError(int errorCode,
                      java.lang.String description)
Information about errors during data delivery. (Called internally to dispatch the event.)
See Also:
HttpErrorEvent

fireHeader

public void fireHeader(java.lang.String field,
                       java.lang.String value)
Fired every time a header line comes in. (Called internally to dispatch the event.)
See Also:
HttpHeaderEvent

fireStartTransfer

public void fireStartTransfer(int direction)
Fired when a document starts transferring (after the headers). (Called internally to dispatch the event.)
See Also:
HttpStartTransferEvent

fireTransfer

public void fireTransfer(int direction,
                         int bytesTransferred,
                         byte[] text)
Fired while a document transfers (delivers document). (Called internally to dispatch the event.)
See Also:
HttpTransferEvent

addHttpEventListener

public void addHttpEventListener(HttpEventListener l)
                          throws java.util.TooManyListenersException

removeHttpEventListener

public void removeHttpEventListener(HttpEventListener l)

IP*Works!

Copyright (c) 1995-2000 by /n software inc. - All rights reserved.