public class HttpOutputStream
extends java.io.OutputStream
OutputStream out = new HttpOutputStream(12345); rsp = con.Post("/cgi-bin/my_cgi", out); out.write(...); out.close(); if (rsp.getStatusCode() >= 300) ...
There are two constructors for this class, one taking a length parameter, and one without any parameters. If the stream is created with a length then the request will be sent with the corresponding Content-length header and anything written to the stream will be written on the socket immediately. This is the preferred way. If the stream is created without a length then one of two things will happen: if, at the time of the request, the server is known to understand HTTP/1.1 then each write() will send the data immediately using the chunked encoding. If, however, either the server version is unknown (because this is first request to that server) or the server only understands HTTP/1.0 then all data will be written to a buffer first, and only when the stream is closed will the request be sent.
Another reason that using the HttpOutputStream(length) constructor is recommended over the HttpOutputStream() one is that some HTTP/1.1 servers do not allow the chunked transfer encoding to be used when POSTing to a cgi script. This is because the way the cgi API is defined the cgi script expects a Content-length environment variable. If the data is sent using the chunked transfer encoding however, then the server would have to buffer all the data before invoking the cgi so that this variable could be set correctly. Not all servers are willing to do this.
If you cannot use the HttpOutputStream(length) constructor and are having problems sending requests (usually a 411 response) then you can try setting the system property HTTPClient.dontChunkRequests to true (this needs to be done either on the command line or somewhere in the code before the HTTPConnection is first accessed). This will prevent the client from using the chunked encoding in this case and will cause the HttpOutputStream to buffer all the data instead, sending it only when close() is invoked.
The behaviour of a request sent with an output stream may differ from
that of a request sent with a data parameter. The reason for this is that
the various modules cannot resend a request which used an output stream.
Therefore such things as authorization and retrying of requests won't be
done by the HTTPClient for such requests. But see HTTPResponse.retryRequest
for a partial
solution.
Constructor and Description |
---|
HttpOutputStream()
Creates an output stream of unspecified length.
|
HttpOutputStream(long length)
This creates an output stream which will take length bytes
of data.
|
Modifier and Type | Method and Description |
---|---|
void |
close()
Closes the stream and causes the data to be sent if it has not already
been done so.
|
long |
getLength()
Returns the number of bytes this stream is willing to accept, or -1
if it is unbounded.
|
NVPair[] |
getTrailers()
Gets the trailers which were set with
setTrailers() . |
void |
reset()
Reset this output stream, so it may be reused in a retried request.
|
void |
setTrailers(NVPair[] trailers)
Sets the trailers to be sent if the output is sent with the
chunked transfer encoding.
|
java.lang.String |
toString()
produces a string describing this stream.
|
void |
write(byte[] buf,
int off,
int len)
Writes an array of bytes on the stream.
|
void |
write(int b)
Writes a single byte on the stream.
|
public HttpOutputStream()
HttpOutputStream(int)
used instead.HttpOutputStream#HttpOutputStream(int)
public HttpOutputStream(long length)
length
- the number of bytes which will be sent over this streampublic long getLength()
public NVPair[] getTrailers()
setTrailers()
.setTrailers(HTTPClient.NVPair[])
public void setTrailers(NVPair[] trailers)
Any trailers set here should be mentioned in a Trailer header in the request (see section 14.40 of draft-ietf-http-v11-spec-rev-06.txt).
This method (and its related getTrailers()
)) are
in this class and not in Request because setting
trailers is something an application may want to do, not only
modules.
trailers
- an array of header fieldspublic void reset()
public void write(int b) throws java.io.IOException, java.lang.IllegalAccessError
write(byte[], int, int)
.write
in class java.io.OutputStream
b
- the byte to writejava.io.IOException
- if any exception is thrown by the socketjava.lang.IllegalAccessError
write(byte[], int, int)
public void write(byte[] buf, int off, int len) throws java.io.IOException, java.lang.IllegalAccessError
write
in class java.io.OutputStream
buf
- an array containing the data to writeoff
- the offset of the data whithin the bufferlen
- the number bytes (starting at off) to writejava.io.IOException
- if any exception is thrown by the socket, or
if writing len bytes would cause more bytes to
be written than this stream is willing to accept.java.lang.IllegalAccessError
- if this stream has not been associated
with a request yetpublic void close() throws java.io.IOException, java.lang.IllegalAccessError
close
in interface java.io.Closeable
close
in interface java.lang.AutoCloseable
close
in class java.io.OutputStream
java.io.IOException
- if any exception is thrown by the underlying
socket, or if too few bytes were written.java.lang.IllegalAccessError
- if this stream has not been associated
with a request yet.public java.lang.String toString()
toString
in class java.lang.Object