|
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 |
java.lang.Object
HTTPClient.HTTPConnection
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):
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 |
public static final java.lang.String version
public static final int HTTP
public static final int HTTPS
public static final int SHTTP
public static final int HTTP_NG
public static final int HTTP_1_0
public static final int HTTP_1_1
public static final int CD_NONE
public static final int CD_HDRS
public static final int CD_0
public static final int CD_CLOSE
public static final int CD_CONTLEN
public static final int CD_CHUNKED
public static final int CD_MP_BR
Constructor Detail |
public HTTPConnection(java.applet.Applet applet) throws ProtocolNotSuppException
applet
- the current appletpublic HTTPConnection(java.lang.String host)
host
- the hostpublic HTTPConnection(java.lang.String host, int port)
host
- the hostport
- the portpublic HTTPConnection(java.lang.String prot, java.lang.String host, int port) throws ProtocolNotSuppException
prot
- the protocolhost
- the hostport
- the port, or -1 for the default portProtocolNotSuppException
- if the protocol is not HTTPpublic HTTPConnection(java.lang.String prot, java.lang.String host, int port, java.net.InetAddress localAddr, int localPort) throws ProtocolNotSuppException
prot
- the protocolhost
- the hostport
- the port, or -1 for the default portlocalAddr
- the local address to bind tolocalPort
- the local port to bind toProtocolNotSuppException
- if the protocol is not HTTPpublic HTTPConnection(java.net.URL url) throws ProtocolNotSuppException
url
- the urlProtocolNotSuppException
- if the protocol is not HTTPpublic HTTPConnection(java.net.URL url, boolean oracleSSL) throws ProtocolNotSuppException
url
- the urlProtocolNotSuppException
- if the protocol is not HTTPHTTPConnection(URL)
, setSSLSocketFactory(javax.net.ssl.SSLSocketFactory)
public HTTPConnection(URI uri) throws ProtocolNotSuppException
uri
- the uriProtocolNotSuppException
- if the protocol is not HTTPMethod Detail |
public HTTPResponse Head(java.lang.String file) throws java.io.IOException, ModuleException
file
- the absolute path of the filejava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.Get(java.lang.String)
public HTTPResponse Head(java.lang.String file, NVPair[] form_data) throws java.io.IOException, ModuleException
file
- the absolute path of the fileform_data
- an array of Name/Value pairsjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.Get(java.lang.String, HTTPClient.NVPair[])
public HTTPResponse Head(java.lang.String file, NVPair[] form_data, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the fileform_data
- an array of Name/Value pairsheaders
- additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.Get(java.lang.String, HTTPClient.NVPair[], HTTPClient.NVPair[])
public HTTPResponse Head(java.lang.String file, java.lang.String query) throws java.io.IOException, ModuleException
file
- the absolute path of the filequery
- the query string; it will be urlencodedjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.Get(java.lang.String, java.lang.String)
public HTTPResponse Head(java.lang.String file, java.lang.String query, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the filequery
- the query string; it will be urlencodedheaders
- additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.Get(java.lang.String, java.lang.String, HTTPClient.NVPair[])
public HTTPResponse Get(java.lang.String file) throws java.io.IOException, ModuleException
file
- the absolute path of the filejava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Get(java.lang.String file, NVPair[] form_data) throws java.io.IOException, ModuleException
file
- the absolute path of the fileform_data
- an array of Name/Value pairsjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Get(java.lang.String file, NVPair[] form_data, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the fileform_data
- an array of Name/Value pairsheaders
- additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Get(java.lang.String file, java.lang.String query) throws java.io.IOException, ModuleException
file
- the absolute path of the filequery
- the queryjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Get(java.lang.String file, java.lang.String query, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the filequery
- the query stringheaders
- additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Post(java.lang.String file) throws java.io.IOException, ModuleException
file
- the absolute path of the filejava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Post(java.lang.String file, NVPair[] form_data) throws java.io.IOException, ModuleException
file
- the absolute path of the fileform_data
- an array of Name/Value pairsjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Post(java.lang.String file, NVPair[] form_data, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the fileform_data
- an array of Name/Value pairsheaders
- additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Post(java.lang.String file, java.lang.String data) throws java.io.IOException, ModuleException
file
- the absolute path of the filedata
- the datajava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.String.getBytes()
public HTTPResponse Post(java.lang.String file, java.lang.String data, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the filedata
- the dataheaders
- additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.String.getBytes()
public HTTPResponse Post(java.lang.String file, byte[] data) throws java.io.IOException, ModuleException
file
- the absolute path of the filedata
- the datajava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Post(java.lang.String file, byte[] data, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the filedata
- the dataheaders
- additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Post(java.lang.String file, HttpOutputStream stream) throws java.io.IOException, ModuleException
file
- the absolute path of the filestream
- the output stream on which the data is writtenjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Post(java.lang.String file, HttpOutputStream stream, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the filestream
- the output stream on which the data is writtenheaders
- additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Put(java.lang.String file, java.lang.String data) throws java.io.IOException, ModuleException
file
- the absolute path of the filedata
- the datajava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.String.getBytes()
public HTTPResponse Put(java.lang.String file, java.lang.String data, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the filedata
- the dataheaders
- additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.String.getBytes()
public HTTPResponse Put(java.lang.String file, byte[] data) throws java.io.IOException, ModuleException
file
- the absolute path of the filedata
- the datajava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Put(java.lang.String file, byte[] data, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the filedata
- the dataheaders
- any additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Put(java.lang.String file, HttpOutputStream stream) throws java.io.IOException, ModuleException
file
- the absolute path of the filestream
- the output stream on which the data is writtenjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Put(java.lang.String file, HttpOutputStream stream, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the filestream
- the output stream on which the data is writtenheaders
- any additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Options(java.lang.String file) throws java.io.IOException, ModuleException
file
- the absolute path of the resource, or "*"java.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Options(java.lang.String file, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the resource, or "*"headers
- the headers containing optional info.java.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Options(java.lang.String file, NVPair[] headers, byte[] data) throws java.io.IOException, ModuleException
file
- the absolute path of the resource, or "*"headers
- the headers containing optional info.data
- any data to be sent in the optional bodyjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Options(java.lang.String file, NVPair[] headers, HttpOutputStream stream) throws java.io.IOException, ModuleException
file
- the absolute path of the resource, or "*"headers
- the headers containing optional info.stream
- an output stream for sending the optional bodyjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Delete(java.lang.String file) throws java.io.IOException, ModuleException
file
- the absolute path of the resourcejava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Delete(java.lang.String file, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the resourceheaders
- additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Trace(java.lang.String file, NVPair[] headers) throws java.io.IOException, ModuleException
file
- the absolute path of the resourceheaders
- additional headersjava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse Trace(java.lang.String file) throws java.io.IOException, ModuleException
file
- the absolute path of the resourcejava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse ExtensionMethod(java.lang.String method, java.lang.String file, byte[] data, NVPair[] headers) throws java.io.IOException, ModuleException
method
- the extension methodfile
- the absolute path of the resource, or nulldata
- optional data, or nullheaders
- optional headers, or nulljava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public HTTPResponse ExtensionMethod(java.lang.String method, java.lang.String file, HttpOutputStream os, NVPair[] headers) throws java.io.IOException, ModuleException
method
- the extension methodfile
- the absolute path of the resource, or nullos
- optional output stream, or nullheaders
- optional headers, or nulljava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public void stop()
Note: there is a small window where a request method such as Get()
may have been invoked but the request has not been built and added to the list. Any request in this window will not be aborted.
public void setDefaultHeaders(NVPair[] headers)
Typical headers you might want to set here are "Accept" and its "Accept-*" relatives, "Connection", "From", "User-Agent", etc.
headers
- an array of header-name/value pairs (do not give the separating ':').public NVPair[] getDefaultHeaders()
public java.lang.String getProtocol()
public java.lang.String getHost()
public int getPort()
public java.lang.String getProxyHost()
public int getProxyPort()
public boolean isCompatibleWith(URI uri)
uri
- the URI to checkpublic void setRawMode(boolean raw)
The default is false.
raw
- if true removes all modules (except for the retry module)removeModule(java.lang.Class)
public static void setDefaultTimeout(int time)
time
- the timeout in milliseconds.setTimeout(int)
public static void setDefaultConnectionTimeout(int time)
time
- the timeout in milliseconds.setTimeout(int)
, setDefaultTimeout(int)
public static int getDefaultTimeout()
setTimeout(int)
public static int getDefaultConnectionTimeout()
setTimeout(int)
public void setTimeout(int time)
resp.getInputStream().close()
should be invoked.
When creating new sockets the connection timeout will limit the time spent doing the host name translation and establishing the connection with the server.
The read timeout influences the reading of the response headers. However, it does not specify a how long, for example, getStatusCode() may take, as might be assumed. Instead it specifies how long a read on the socket may take. If the response dribbles in slowly with packets arriving quicker than the timeout then the method will complete normally. I.e. the exception is only thrown if nothing arrives on the socket for the specified time. Furthermore, the timeout only influences the reading of the headers, not the reading of the body.
Read Timeouts are associated with responses, so that you may change this value before each request and it won't affect the reading of responses to previous requests.
time
- the time in milliseconds. A time of 0 means wait indefinitely.stop()
public void setConnectionTimeout(int time)
time
- the timeout in milliseconds.setTimeout(int)
, setDefaultTimeout(int)
public int getTimeout()
setTimeout(int)
public int getConnectionTimeout()
setTimeout(int)
public void setAllowUserInteraction(boolean allow)
allow
- if true allows modules to interact with user.public boolean getAllowUserInteraction()
public static void setDefaultAllowUserInteraction(boolean allow)
allow
- if true allows modules to interact with user.public static boolean getDefaultAllowUserInteraction()
public static java.lang.Class[] getDefaultModules()
public static boolean addDefaultModule(java.lang.Class module, int pos)
Example:
HTTPConnection.addDefaultModule(Class.forName("HTTPClient.CookieModule"), 1);adds the cookie module as the second module in the list.
The default list is created at class initialization time from the property HTTPClient.Modules. This must contain a "|" separated list of classes in the order they're to be invoked. If this property is not set it defaults to: "HTTPClient.RetryModule | HTTPClient.CookieModule | HTTPClient.RedirectionModule | HTTPClient.AuthorizationModule | HTTPClient.DefaultModule | HTTPClient.TransferEncodingModule | HTTPClient.ContentMD5Module | HTTPClient.ContentEncodingModule"
module
- the module's Class objectpos
- the position of this module in the list; if pos >= 0 then this is the absolute position in the list (0 is the first position); if pos < 0 then this is the position relative to the end of the list (-1 means the last element, -2 the second to last element, etc).java.lang.ArrayIndexOutOfBoundsException
- if pos > list-size or if pos < -(list-size).java.lang.ClassCastException
- if module does not implement the HTTPClientModule interface.java.lang.RuntimeException
- if module cannot be instantiated.HTTPClientModule
public static boolean removeDefaultModule(java.lang.Class module)
module
- the module's Class objectpublic java.lang.Class[] getModules()
public boolean addModule(java.lang.Class module, int pos)
module
- the module's Class objectpos
- the position of this module in the list; if pos >= 0 then this is the absolute position in the list (0 is the first position); if pos < 0 then this is the position relative to the end of the list (-1 means the last element, -2 the second to last element, etc).java.lang.ArrayIndexOutOfBoundsException
- if pos > list-size or if pos < -(list-size).java.lang.ClassCastException
- if module does not implement the HTTPClientModule interface.java.lang.RuntimeException
- if module cannot be instantiated.HTTPClientModule
public boolean removeModule(java.lang.Class module)
module
- the module's Class objectpublic void setContext(java.lang.Object context)
The context may be any object. Contexts are considered equal if equals()
returns true. Examples of useful context objects are threads (e.g. if you are running multiple clients, one per thread) and sockets (e.g. if you are implementing a gateway).
When a new HTTPConnection is created it is initialized with a default context which is the same for all instances. This method must be invoked immediately after a new HTTPConnection is created and before any request method is invoked. Furthermore, this method may only be called once (i.e. the context is "sticky").
context
- the new context; must be non-nulljava.lang.IllegalArgumentException
- if context is nulljava.lang.IllegalStateException
- if the context has already been setpublic java.lang.Object getContext()
setContext()
hasn't been invokedsetContext(java.lang.Object)
public static java.lang.Object getDefaultContext()
setContext(java.lang.Object)
public void addDigestAuthorization(java.lang.String realm, java.lang.String user, java.lang.String passwd)
This is a convenience method and just invokes the corresponding method in AuthorizationInfo.
realm
- the realmuser
- the usernamepasswd
- the passwordAuthorizationInfo.addDigestAuthorization(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String)
public void addBasicAuthorization(java.lang.String realm, java.lang.String user, java.lang.String passwd)
This is a convenience method and just invokes the corresponding method in AuthorizationInfo.
realm
- the realmuser
- the usernamepasswd
- the passwordAuthorizationInfo.addBasicAuthorization(java.lang.String, int, java.lang.String, java.lang.String, java.lang.String)
public static void setProxyServer(java.lang.String host, int port)
In an application or using the Appletviewer an alternative to this method is to set the following properties (either in the properties file or on the command line): http.proxyHost and http.proxyPort. Whether http.proxyHost is set or not determines whether a proxy server is used.
If the proxy server requires authorization and you wish to set this authorization information in the code, then you may use any of the AuthorizationInfo.addXXXAuthorization() methods to do so. Specify the same host and port as in this method. If you have not given any authorization info and the proxy server requires authorization then you will be prompted for the necessary info via a popup the first time you do a request.
host
- the host on which the proxy server resides.port
- the port the proxy server is listening on.setCurrentProxy(java.lang.String, int)
public void setCurrentProxy(java.lang.String host, int port)
Note that if you set a proxy for the connection using this method, and a request made over this connection is redirected to a different server, then the connection used for new server will not pick this proxy setting, but instead will use the default proxy settings.
host
- the host the proxy runs onport
- the port the proxy is listening onsetProxyServer(java.lang.String, int)
public static void dontProxyFor(java.lang.String host) throws ParseException
setProxyServer()
.
The host may be any of:
The two properties HTTPClient.nonProxyHosts and http.nonProxyHosts are used when this class is loaded to initialize the list of non-proxy hosts. The second property is only read if the first one is not set; the second property is also used the JDK's URLConnection. These properties must contain a "|" separated list of entries which conform to the above rules for the host parameter (e.g. "11.22.33.44|.disney.com").
host
- a host name, domain name, IP-address or IP-subnet.ParseException
- if the length of the netmask does not match the length of the IP-addresspublic static void dontProxyFor(java.lang.String[] hosts)
hosts
- The list of hosts to setdontProxyFor(java.lang.String)
public static boolean doProxyFor(java.lang.String host) throws ParseException
dontProxyFor()
uses, i.e. this is used to undo a dontProxyFor()
setting. The syntax for host is specified in dontProxyFor()
.host
- a host name, domain name, IP-address or IP-subnet.ParseException
- if the length of the netmask does not match the length of the IP-addressdontProxyFor(java.lang.String)
public static void setSocksServer(java.lang.String host)
The code will try to determine the SOCKS version to use at connection time. This might fail for a number of reasons, however, in which case you must specify the version explicitly.
host
- the host on which the proxy server resides. The port used is the default port 1080.setSocksServer(java.lang.String, int, int)
public static void setSocksServer(java.lang.String host, int port)
The code will try to determine the SOCKS version to use at connection time. This might fail for a number of reasons, however, in which case you must specify the version explicitly.
host
- the host on which the proxy server resides.port
- the port the proxy server is listening on.setSocksServer(java.lang.String, int, int)
public static void setSocksServer(java.lang.String host, int port, int version) throws SocksException
In an application or using the Appletviewer an alternative to this method is to set the following properties (either in the properties file or on the command line): HTTPClient.socksHost, HTTPClient.socksPort and HTTPClient.socksVersion. Whether HTTPClient.socksHost is set or not determines whether a SOCKS server is used; if HTTPClient.socksPort is not set it defaults to 1080; if HTTPClient.socksVersion is not set an attempt will be made to automatically determine the version used by the server.
Note: If you have also set a proxy server then a connection will be made to the SOCKS server, which in turn then makes a connection to the proxy server (possibly via other SOCKS servers), which in turn makes the final connection.
If the proxy server is running SOCKS version 5 and requires username/password authorization, and you wish to set this authorization information in the code, then you may use the AuthorizationInfo.addAuthorization() method to do so. Specify the same host and port as in this method, give the scheme "SOCKS5" and the realm "USER/PASS", set the cookie to null and the params to an array containing a single NVPair in turn containing the username and password. Example:
NVPair[] up = { new NVPair(username, password) }; AuthorizationInfo.addAuthorization(host, port, "SOCKS5", "USER/PASS", null, up);If you have not given any authorization info and the proxy server requires authorization then you will be prompted for the necessary info via a popup the first time you do a request.
host
- the host on which the proxy server resides.port
- the port the proxy server is listening on.version
- the SOCKS version the server is running. Currently this must be '4' or '5'.SocksException
- If version is not '4' or '5'.protected final HTTPResponse setupRequest(java.lang.String method, java.lang.String resource, NVPair[] headers, byte[] entity, HttpOutputStream stream) throws java.io.IOException, ModuleException
method
- GET, POST, etc.resource
- the resourceheaders
- an array of headers to be usedentity
- the entity (or null)stream
- the output stream (or null) - only one of stream and entity may be non-nulljava.io.IOException
- when an exception is returned from the socket.ModuleException
- if an exception is encountered in any module.public java.lang.String toString()
public void connect() throws java.io.IOException
java.io.IOException
getSSLSession()
public void addTrustPoint(byte[] certificate)
certificate
- the certificate to add to the trusted listpublic void addTrustPoint(java.lang.String certificate)
certificate
- the certificate to add to the trusted listpublic void addTrustPoint(java.security.cert.Certificate certificate) throws java.security.cert.CertificateEncodingException
certificate
- the certificate to add to the trusted listjava.security.cert.CertificateEncodingException
public static void setDefaultSSLSocketFactory(javax.net.ssl.SSLSocketFactory factory)
If no SSLSocketFactory is specified for an HTTPConnection (either by default or via a call to HTTPConnection.setSSLSocketFactory) then HTTPClient will attempt to use the Oracle implementation of SSL if it is available on the classpath. Otherwise it will use SSLSocketFactory.getDefault().
factory
- the SSLSocketFactory to be used by default.public void setSSLSocketFactory(javax.net.ssl.SSLSocketFactory factory)
factory
- the SSLSocketFactory used for https in this HTTPConnection.public OracleSSLCredential getSSLCredential()
public java.lang.String[] getSSLEnabledCipherSuites()
public javax.net.ssl.SSLSession getSSLSession()
connect()
public javax.net.ssl.SSLSocketFactory getSSLSocketFactory()
public java.net.Socket getSSLSocket(java.net.Socket proxy) throws java.io.IOException
java.io.IOException
public void setSSLCredential(OracleSSLCredential cred)
cred
- the credential object that will be used for the connection.public void setSSLEnabledCipherSuites(java.lang.String[] cipherSuites)
cipherSuites
- Names of all the cipher suites to enable.java.lang.IllegalArgumentException
- when one of the ciphers named by the parameter is not supported.getSSLEnabledCipherSuites()
public java.lang.String getQueryEncoding()
protected void finalize() throws java.lang.Throwable
java.lang.Throwable
public void setQueryEncoding(java.lang.String encoding)
encoding
- the Java encoding
|
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 |