HTTPConnection (Oracle Application Server HTTPClient API Reference)

Overview

Package

Class

Tree

Deprecated

Index

Help

Oracle Application Server HTTPClient API Reference
10g Release 2 (10.1.2)
B14020-02

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

HTTPClient
Class HTTPConnection

java.lang.Object HTTPClient.HTTPConnection

All Implemented Interfaces:: HTTPClient.GlobalConstants, HTTPClientModuleConstants

public class HTTPConnection
extends java.lang.Object
implements HTTPClient.GlobalConstants, HTTPClientModuleConstants

This class implements http protocol requests; it contains most of HTTP/1.1 and ought to be unconditionally compliant. Redirections are automatically handled, and authorizations requests are recognized and dealt with via an authorization handler. Only full HTTP/1.0 and HTTP/1.1 requests are generated. HTTP/1.1, HTTP/1.0 and HTTP/0.9 responses are recognized.

Using the HTTPClient should be quite simple. First add the import statement 'import HTTPClient.*;' to your file(s). Request can then be sent using one of the methods Head(), Get(), Post(), etc in HTTPConnection. These methods all return an instance of HTTPResponse which has methods for accessing the response headers (getHeader(), getHeaderAsInt(), etc), various response info (getStatusCode(), getReasonLine(), etc) and the reponse data (getData(), getText(), and getInputStream()). Following are some examples.

If this is in an applet you can retrieve files from your server as follows:

     try
     {
         HTTPConnection con = new HTTPConnection(this);
         HTTPResponse   rsp = con.Get("/my_file");
         if (rsp.getStatusCode() >= 300)
         {
             System.err.println("Received Error: "+rsp.getReasonLine());
             System.err.println(rsp.getText());
         }
         else
             data = rsp.getData();

         rsp = con.Get("/another_file");
         if (rsp.getStatusCode() >= 300)
         {
             System.err.println("Received Error: "+rsp.getReasonLine());
             System.err.println(rsp.getText());
         }
         else
             other_data = rsp.getData();
     }
     catch (IOException ioe)
     {
         System.err.println(ioe.toString());
     }
     catch (ModuleException me)
     {
         System.err.println("Error handling request: " + me.getMessage());
     }

This will get the files "/my_file" and "/another_file" and put their contents into byte[]'s accessible via getData(). Note that you need to only create a new HTTPConnection when sending a request to a new server (different host or port); although you may create a new HTTPConnection for every request to the same server this not recommended, as various information about the server is cached after the first request (to optimize subsequent requests) and persistent connections are used whenever possible.

To POST form data you would use something like this (assuming you have two fields called name and e-mail, whose contents are stored in the variables name and email):

     try
     {
         NVPair form_data[] = new NVPair[2];
         form_data[0] = new NVPair("name", name);
         form_data[1] = new NVPair("e-mail", email);

         HTTPConnection con = new HTTPConnection(this);
         HTTPResponse   rsp = con.Post("/cgi-bin/my_script", form_data);
         if (rsp.getStatusCode() >= 300)
         {
             System.err.println("Received Error: "+rsp.getReasonLine());
             System.err.println(rsp.getText());
         }
         else
             stream = rsp.getInputStream();
     }
     catch (IOException ioe)
     {
         System.err.println(ioe.toString());
     }
     catch (ModuleException me)
     {
         System.err.println("Error handling request: " + me.getMessage());
     }

Here the response data is read at leasure via an InputStream instead of all at once into a byte[].

As another example, if you have a URL you're trying to send a request to you would do something like the following:

     try
     {
         URL url = new URL("http://www.mydomain.us/test/my_file");
         HTTPConnection con = new HTTPConnection(url);
         HTTPResponse   rsp = con.Put(url.getFile(), "Hello World");
         if (rsp.getStatusCode() >= 300)
         {
             System.err.println("Received Error: "+rsp.getReasonLine());
             System.err.println(rsp.getText());
         }
         else
             text = rsp.getText();
     }
     catch (IOException ioe)
     {
         System.err.println(ioe.toString());
     }
     catch (ModuleException me)
     {
         System.err.println("Error handling request: " + me.getMessage());
     }

There are a whole number of methods for each request type; however the general forms are ([...] means that the enclosed is optional):

Head ( file [, form-data [, headers ] ] )
Head ( file [, query [, headers ] ] )
Get ( file [, form-data [, headers ] ] )
Get ( file [, query [, headers ] ] )
Post ( file [, form-data [, headers ] ] )
Post ( file [, data [, headers ] ] )
Post ( file [, stream [, headers ] ] )
Put ( file , data [, headers ] )
Put ( file , stream [, headers ] )
Delete ( file [, headers ] )
Options ( file [, headers [, data] ] )
Options ( file [, headers [, stream] ] )
Trace ( file [, headers ] )

Field Summary
`static int`	`CD_0` Content delimiter- no body
`static int`	`CD_CHUNKED` Content delimiter - via chunked transfer encoding
`static int`	`CD_CLOSE` Content delimiter - by closing connection
`static int`	`CD_CONTLEN` Content delimiter - via the Content-Length header
`static int`	`CD_HDRS` Content delimiter - reading headers/trailers
`static int`	`CD_MP_BR` Content delimiter - via multipart/byteranges
`static int`	`CD_NONE` Content delimiter - raw read from the stream
`static int`	`HTTP` plain http
`static int`	`HTTP_1_0` HTTP 1.0
`static int`	`HTTP_1_1` HTTP 1.1
`static int`	`HTTP_NG` http next-generation
`static int`	`HTTPS` http on top of SSL
`static int`	`SHTTP` secure http
`static java.lang.String`	`version` The current version of this package.

Fields inherited from interface HTTPClient.HTTPClientModuleConstants

REQ_CONTINUE, REQ_NEWCON_RST, REQ_NEWCON_SND, REQ_RESPONSE, REQ_RESTART, REQ_RETURN, REQ_SHORTCIRC, RSP_CONTINUE, RSP_NEWCON_REQ, RSP_NEWCON_SND, RSP_REQUEST, RSP_RESTART, RSP_SEND, RSP_SHORTCIRC

Constructor Summary
`HTTPConnection(java.applet.Applet applet)` Constructs a connection to the host from where the applet was loaded.
`HTTPConnection(java.lang.String host)` Constructs a connection to the specified host on port 80
`HTTPConnection(java.lang.String host, int port)` Constructs a connection to the specified host on the specified port
`HTTPConnection(java.lang.String prot, java.lang.String host, int port)` Constructs a connection to the specified host on the specified port, using the specified protocol (currently only "http" is supported).
`HTTPConnection(java.lang.String prot, java.lang.String host, int port, java.net.InetAddress localAddr, int localPort)` Constructs a connection to the specified host on the specified port, using the specified protocol (currently only "http" is supported), local address, and local port.
`HTTPConnection(URI uri)` Constructs a connection to the host (port) as given in the uri.
`HTTPConnection(java.net.URL url)` Constructs a connection to the host (port) as given in the url.
`HTTPConnection(java.net.URL url, boolean oracleSSL)` Deprecated. This constructor has been deprecated. Please use the HTTPConnection(URL) constructor. OracleSSL is the default SSL provider for HTTPS connections. To change this default, use HTTPConnection.setSSLSocketFactory.

Method Summary
`void`	`addBasicAuthorization(java.lang.String realm, java.lang.String user, java.lang.String passwd)` Adds an authorization entry for the "basic" authorization scheme to the list.
`static boolean`	`addDefaultModule(java.lang.Class module, int pos)` Adds a module to the default list.
`void`	`addDigestAuthorization(java.lang.String realm, java.lang.String user, java.lang.String passwd)` Adds an authorization entry for the "digest" authorization scheme to the list.
`boolean`	`addModule(java.lang.Class module, int pos)` Adds a module to the current list.
`void`	`addTrustPoint(byte[] certificate)` Adds the specified trust point to the list of trusted certificates for this connection's OracleSSLCredential.
`void`	`addTrustPoint(java.security.cert.Certificate certificate)` Adds the specified trust point to the list of trusted certificates for this connection's OracleSSLCredential.
`void`	`addTrustPoint(java.lang.String certificate)` Adds the specified trust point to the list of trusted certificates for this connection's OracleSSLCredential.
`void`	`connect()` Connects the socket to the server, but does not send any data.
`HTTPResponse`	`Delete(java.lang.String file)` Requests that `file` be DELETEd from the server.
`HTTPResponse`	`Delete(java.lang.String file, NVPair[] headers)` Requests that `file` be DELETEd from the server.
`static void`	`dontProxyFor(java.lang.String host)` Add `host` to the list of hosts which should be accessed directly, not via any proxy set by `setProxyServer()`.
`static void`	`dontProxyFor(java.lang.String[] hosts)` Convenience method to add a number of hosts at once.
`static boolean`	`doProxyFor(java.lang.String host)` Remove `host` from the list of hosts for which the proxy should not be used.
`HTTPResponse`	`ExtensionMethod(java.lang.String method, java.lang.String file, byte[] data, NVPair[] headers)` This is here to allow an arbitrary, non-standard request to be sent.
`HTTPResponse`	`ExtensionMethod(java.lang.String method, java.lang.String file, HttpOutputStream os, NVPair[] headers)` This is here to allow an arbitrary, non-standard request to be sent.
`protected void`	`finalize()` Added as a safety net, in-case HTTPConnection object is not referenced any more, make sure to release the sockets held by this.
`HTTPResponse`	`Get(java.lang.String file)` GETs the file.
`HTTPResponse`	`Get(java.lang.String file, NVPair[] form_data)` GETs the file with a query consisting of the specified form-data.
`HTTPResponse`	`Get(java.lang.String file, NVPair[] form_data, NVPair[] headers)` GETs the file with a query consisting of the specified form-data.
`HTTPResponse`	`Get(java.lang.String file, java.lang.String query)` GETs the file using the specified query string.
`HTTPResponse`	`Get(java.lang.String file, java.lang.String query, NVPair[] headers)` GETs the file using the specified query string.
`boolean`	`getAllowUserInteraction()` returns whether modules are allowed to prompt or popup dialogs if neccessary.
`int`	`getConnectionTimeout()` Gets the read timeout used for reading response data.
`java.lang.Object`	`getContext()` Returns the current context.
`static boolean`	`getDefaultAllowUserInteraction()` Gets the default allow-user-action.
`static int`	`getDefaultConnectionTimeout()` Gets the default read timeout value to be used for each new HTTPConnection.
`static java.lang.Object`	`getDefaultContext()` Returns the default context.
`NVPair[]`	`getDefaultHeaders()` Gets the current list of default http headers.
`static java.lang.Class[]`	`getDefaultModules()` Returns the default list of modules.
`static int`	`getDefaultTimeout()` Gets the default read timeout value to be used for each new HTTPConnection.
`java.lang.String`	`getHost()` Returns the host this connection is talking to.
`java.lang.Class[]`	`getModules()` Returns the list of modules used currently.
`int`	`getPort()` Returns the port this connection connects to.
`java.lang.String`	`getProtocol()` Returns the protocol this connection is talking.
`java.lang.String`	`getProxyHost()` Returns the host of the proxy this connection is using.
`int`	`getProxyPort()` Returns the port of the proxy this connection is using.
`java.lang.String`	`getQueryEncoding()` The current Java encoding used for the queries part of a URL Initially null.
`OracleSSLCredential`	`getSSLCredential()` Returns the SSLCredential used by this socket
`java.lang.String[]`	`getSSLEnabledCipherSuites()` Returns the list of cipher suites that are enabled for the https connection
`javax.net.ssl.SSLSession`	`getSSLSession()` Returns the ssl session information for the ssl connection or null if no ssl connection has been established
`java.net.Socket`	`getSSLSocket(java.net.Socket proxy)` Obtains an new SSL Socket to be used for HTTPS connections If setSSLCredentials() or setSSLCipherSuites() were not called prior to this call, the property settings are checked
`javax.net.ssl.SSLSocketFactory`	`getSSLSocketFactory()` Returns the socket factory used to create SSL sockets
`int`	`getTimeout()` Gets the read timeout used for reading response data.
`HTTPResponse`	`Head(java.lang.String file)` Sends the HEAD request.
`HTTPResponse`	`Head(java.lang.String file, NVPair[] form_data)` Sends the HEAD request.
`HTTPResponse`	`Head(java.lang.String file, NVPair[] form_data, NVPair[] headers)` Sends the HEAD request.
`HTTPResponse`	`Head(java.lang.String file, java.lang.String query)` Sends the HEAD request.
`HTTPResponse`	`Head(java.lang.String file, java.lang.String query, NVPair[] headers)` Sends the HEAD request.
`boolean`	`isCompatibleWith(URI uri)` See if the given uri is compatible with this connection.
`HTTPResponse`	`Options(java.lang.String file)` Request OPTIONS from the server.
`HTTPResponse`	`Options(java.lang.String file, NVPair[] headers)` Request OPTIONS from the server.
`HTTPResponse`	`Options(java.lang.String file, NVPair[] headers, byte[] data)` Request OPTIONS from the server.
`HTTPResponse`	`Options(java.lang.String file, NVPair[] headers, HttpOutputStream stream)` Request OPTIONS from the server.
`HTTPResponse`	`Post(java.lang.String file)` POSTs to the specified file.
`HTTPResponse`	`Post(java.lang.String file, byte[] data)` POSTs the raw data to the specified file.
`HTTPResponse`	`Post(java.lang.String file, byte[] data, NVPair[] headers)` POSTs the raw data to the specified file using the specified headers.
`HTTPResponse`	`Post(java.lang.String file, HttpOutputStream stream)` POSTs the data written to the output stream to the specified file.
`HTTPResponse`	`Post(java.lang.String file, HttpOutputStream stream, NVPair[] headers)` POSTs the data written to the output stream to the specified file using the specified headers.
`HTTPResponse`	`Post(java.lang.String file, NVPair[] form_data)` POSTs form-data to the specified file.
`HTTPResponse`	`Post(java.lang.String file, NVPair[] form_data, NVPair[] headers)` POST's form-data to the specified file using the specified headers.
`HTTPResponse`	`Post(java.lang.String file, java.lang.String data)` POSTs the data to the specified file.
`HTTPResponse`	`Post(java.lang.String file, java.lang.String data, NVPair[] headers)` POSTs the data to the specified file using the specified headers.
`HTTPResponse`	`Put(java.lang.String file, byte[] data)` PUTs the raw data into the specified file.
`HTTPResponse`	`Put(java.lang.String file, byte[] data, NVPair[] headers)` PUTs the raw data into the specified file using the additional headers.
`HTTPResponse`	`Put(java.lang.String file, HttpOutputStream stream)` PUTs the data written to the output stream into the specified file.
`HTTPResponse`	`Put(java.lang.String file, HttpOutputStream stream, NVPair[] headers)` PUTs the data written to the output stream into the specified file using the additional headers.
`HTTPResponse`	`Put(java.lang.String file, java.lang.String data)` PUTs the data into the specified file.
`HTTPResponse`	`Put(java.lang.String file, java.lang.String data, NVPair[] headers)` PUTs the data into the specified file using the additional headers for the request.
`static boolean`	`removeDefaultModule(java.lang.Class module)` Removes a module from the default list.
`boolean`	`removeModule(java.lang.Class module)` Removes a module from the current list.
`void`	`setAllowUserInteraction(boolean allow)` Controls whether modules are allowed to prompt the user or pop up dialogs if neccessary.
`void`	`setConnectionTimeout(int time)` Sets the connection timeout values for this HTTPConnection.
`void`	`setContext(java.lang.Object context)` Sets the current context.
`void`	`setCurrentProxy(java.lang.String host, int port)` Sets the proxy used by this instance.
`static void`	`setDefaultAllowUserInteraction(boolean allow)` Sets the default allow-user-action.
`static void`	`setDefaultConnectionTimeout(int time)` Sets the default connection timeout values to be used for each new HTTPConnection.
`void`	`setDefaultHeaders(NVPair[] headers)` Sets the default http headers to be sent with each request.
`static void`	`setDefaultSSLSocketFactory(javax.net.ssl.SSLSocketFactory factory)` Set the default SSLSocketFactory for use by HTTPClient.
`static void`	`setDefaultTimeout(int time)` Sets the default read and connection timeout values to be used for each new HTTPConnection.
`static void`	`setProxyServer(java.lang.String host, int port)` Sets the default proxy server to use.
`void`	`setQueryEncoding(java.lang.String encoding)` Sets the Java encoding to be used for the query parts of URL's in requests If it is null the System default encoding is used.
`void`	`setRawMode(boolean raw)` Deprecated. This is not really needed anymore; in V0.2 request were synchronous and therefore to do pipelining you needed to disable the processing of responses.
`static void`	`setSocksServer(java.lang.String host)` Sets the SOCKS server to use.
`static void`	`setSocksServer(java.lang.String host, int port)` Sets the SOCKS server to use.
`static void`	`setSocksServer(java.lang.String host, int port, int version)` Sets the SOCKS server to use.
`void`	`setSSLCredential(OracleSSLCredential cred)` Sets the OracleSSLCredential object for use in SSL connections
`void`	`setSSLEnabledCipherSuites(java.lang.String[] cipherSuites)` Controls which particular cipher suites are enabled for use on this connection.
`void`	`setSSLSocketFactory(javax.net.ssl.SSLSocketFactory factory)` Sets the SSLSocketFactory that will be used for https connections
`void`	`setTimeout(int time)` Sets the timeouts to be used for creating connections and reading responses.
`protected HTTPResponse`	`setupRequest(java.lang.String method, java.lang.String resource, NVPair[] headers, byte[] entity, HttpOutputStream stream)` Sets up the request, creating the list of headers to send and creating instances of the modules.
`void`	`stop()` Aborts all the requests currently in progress on this connection and closes all associated sockets.
`java.lang.String`	`toString()` Generates a string of the form protocol://host.domain:port .
`HTTPResponse`	`Trace(java.lang.String file)` Requests a TRACE.
`HTTPResponse`	`Trace(java.lang.String file, NVPair[] headers)` Requests a TRACE.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

version

public static final java.lang.String version

The current version of this package.

See Also:: Constant Field Values

HTTP

public static final int HTTP

plain http

See Also:: Constant Field Values

HTTPS

public static final int HTTPS

http on top of SSL

See Also:: Constant Field Values

SHTTP

public static final int SHTTP

secure http

See Also:: Constant Field Values

HTTP_NG

public static final int HTTP_NG

http next-generation

See Also:: Constant Field Values

HTTP_1_0

public static final int HTTP_1_0

HTTP 1.0

See Also:: Constant Field Values

HTTP_1_1

public static final int HTTP_1_1

HTTP 1.1

See Also:: Constant Field Values

CD_NONE

public static final int CD_NONE

Content delimiter - raw read from the stream

See Also:: Constant Field Values

CD_HDRS

public static final int CD_HDRS

Content delimiter - reading headers/trailers

See Also:: Constant Field Values

CD_0

public static final int CD_0

Content delimiter- no body

See Also:: Constant Field Values

CD_CLOSE

public static final int CD_CLOSE

Content delimiter - by closing connection

See Also:: Constant Field Values

CD_CONTLEN

public static final int CD_CONTLEN

Content delimiter - via the Content-Length header

See Also:: Constant Field Values

CD_CHUNKED

public static final int CD_CHUNKED

Content delimiter - via chunked transfer encoding

See Also:: Constant Field Values

CD_MP_BR

public static final int CD_MP_BR

Content delimiter - via multipart/byteranges

See Also:: Constant Field Values

Constructor Detail

HTTPConnection

public HTTPConnection(java.applet.Applet applet)
               throws ProtocolNotSuppException

Constructs a connection to the host from where the applet was loaded. Note that current security policies only let applets connect home.
Parameters:: applet - the current applet

HTTPConnection

public HTTPConnection(java.lang.String host)

Constructs a connection to the specified host on port 80
Parameters:: host - the host

HTTPConnection

public HTTPConnection(java.lang.String host,
                      int port)

Constructs a connection to the specified host on the specified port
Parameters:: host - the host; port - the port

HTTPConnection

public HTTPConnection(java.lang.String prot,
                      java.lang.String host,
                      int port)
               throws ProtocolNotSuppException

Constructs a connection to the specified host on the specified port, using the specified protocol (currently only "http" is supported).
Parameters:: prot - the protocol; host - the host; port - the port, or -1 for the default port
Throws:: ProtocolNotSuppException - if the protocol is not HTTP

HTTPConnection

public HTTPConnection(java.lang.String prot,
                      java.lang.String host,
                      int port,
                      java.net.InetAddress localAddr,
                      int localPort)
               throws ProtocolNotSuppException

Constructs a connection to the specified host on the specified port, using the specified protocol (currently only "http" is supported), local address, and local port.
Parameters:: prot - the protocol; host - the host; port - the port, or -1 for the default port; localAddr - the local address to bind to; localPort - the local port to bind to
Throws:: ProtocolNotSuppException - if the protocol is not HTTP

HTTPConnection

public HTTPConnection(java.net.URL url)
               throws ProtocolNotSuppException

Constructs a connection to the host (port) as given in the url.
Parameters:: url - the url
Throws:: ProtocolNotSuppException - if the protocol is not HTTP

HTTPConnection

public HTTPConnection(java.net.URL url,
                      boolean oracleSSL)
               throws ProtocolNotSuppException

Deprecated. This constructor has been deprecated. Please use the HTTPConnection(URL) constructor. OracleSSL is the default SSL provider for HTTPS connections. To change this default, use HTTPConnection.setSSLSocketFactory.; Constructs a connection to the host (port) as given in the url.
Parameters:: url - the url
Throws:: ProtocolNotSuppException - if the protocol is not HTTP
See Also:: HTTPConnection(URL), setSSLSocketFactory(javax.net.ssl.SSLSocketFactory)

HTTPConnection

public HTTPConnection(URI uri)
               throws ProtocolNotSuppException

Constructs a connection to the host (port) as given in the uri.
Parameters:: uri - the uri
Throws:: ProtocolNotSuppException - if the protocol is not HTTP

Method Detail