public interface OutboundRequest
An OutboundRequest
can be used to write out the
contents of the request and to read in the response.
The communication protocol used by the implementation of this
interface must guarantee that for each instance of this interface,
any request data must only be delivered to the recipient (in the
form of an InboundRequest
passed to RequestDispatcher.dispatch
) at most
once. The getDeliveryStatus
method
can be used to determine whether or not at least partial delivery
of the request might have occurred.
When finished using an OutboundRequest
, in order to
allow the implementation to free resources associated with the
request, users should either invoke close
on the
streams returned by the getRequestOutputStream
and
getResponseInputStream
methods, or invoke the
abort
method.
InboundRequest
Modifier and Type | Method and Description |
---|---|
void |
abort()
Terminates this request, freeing all associated resources.
|
boolean |
getDeliveryStatus()
Returns
false if it is guaranteed that no data
written for this request has been processed by the recipient. |
OutputStream |
getRequestOutputStream()
Returns an
OutputStream to write the request data
to. |
InputStream |
getResponseInputStream()
Returns an
InputStream to read the response data
from. |
InvocationConstraints |
getUnfulfilledConstraints()
Returns the requirements that must be at least partially
implemented by higher layers in order to fully satisfy the
requirements for this request.
|
void |
populateContext(Collection context)
Populates the supplied collection with context information
representing this request.
|
void populateContext(Collection context)
context
- the context collection to populateNullPointerException
- if context
is
null
UnsupportedOperationException
- if context
is unmodifiable and if any elements need to be addedInvocationConstraints getUnfulfilledConstraints()
For any given constraint, there must be a clear delineation
of which aspects (if any) must be implemented by the transport
layer. This method must not return a constraint (as a
requirement or a preference, directly or as an element of
another constraint) unless this request implements all of those
aspects. Also, this method must not return a constraint for
which all aspects must be implemented by the transport layer.
Most of the constraints in the net.jini.core.constraint
package must be fully implemented by the transport layer and
thus must not be returned by this method; the one exception is
Integrity
, for which the transport layer is responsible
for the data integrity aspect and higher layers are responsible
for the code integrity aspect.
For any ConstraintAlternatives
in the constraints
for this request, this method should only return a
corresponding constraint if all of the alternatives satisfied
by this request need to be at least partially implemented by
higher layers in order to be fully satisfied.
OutputStream getRequestOutputStream()
OutputStream
to write the request data
to. The sequence of bytes written to the returned stream will
be the sequence of bytes sent as the body of this request.
After the entirety of the request has been written to the
stream, the stream's close
method must be invoked
to ensure complete delivery of the request. It is possible
that none of the data written to the returned stream will be
delivered before close
has been invoked (even if
the stream's flush
method had been invoked at any
time). Note, however, that some or all of the data written to
the stream may be delivered to (and processed by) the recipient
before the stream's close
method has been invoked.
After the stream's close
method has been
invoked, no more data may be written to the stream; writes
subsequent to a close
invocation will fail with an
IOException
.
If this method is invoked more than once, it will always return the identical stream object that it returned the first time (although the stream may be in a different state than it was upon return from the first invocation).
InputStream getResponseInputStream()
InputStream
to read the response data
from. The sequence of bytes produced by reading from the
returned stream will be the sequence of bytes received as the
response data. When the entirety of the response has been
successfully read, reading from the stream will indicate an
EOF.
Users of an OutboundRequest
must not expect any
data to be available from the returned stream before the
close
method has been invoked on the stream
returned by getRequestOutputStream
; in other
words, the user's request/response protocol must not require
any part of a request to be a function of any part of its
response.
It is possible, however, for data to be available from the
returned stream before the close
method has been
invoked on, or even before the entirety of the request has been
written to, the stream returned by
getRequestOutputStream
. Because such an early
response might indicate, depending on the user's
request/response protocol, that the recipient will not consider
the entirety of the request, perhaps due to an error or other
abnormal condition, the user may wish to process it
expeditiously, rather than continuing to write the remainder of
the request.
Invoking the close
method of the returned
stream will cause any subsequent read operations on the stream
to fail with an IOException
, although it will not
terminate this request as a whole; in particular, the request
may still be subsequently written to the stream returned by the
getRequestOutputStream
method. After
close
has been invoked on both the returned stream
and the stream returned by getRequestOutputStream
,
the implementation may free all resources associated with this
request.
If this method is invoked more than once, it will always return the identical stream object that it returned the first time (although the stream may be in a different state than it was upon return from the first invocation).
boolean getDeliveryStatus()
false
if it is guaranteed that no data
written for this request has been processed by the recipient.
This guarantee remains valid until any subsequent I/O operation
has been attempted on this request.
If this method returns true
, then data written for
this request may have been at least partially processed by the
recipient (the RequestDispatcher
receiving the
corresponding InboundRequest
).false
if data written for this request has
definitely not been processed by the recipient, and
true
if data written for this request may have
been at least partially processed by the recipientvoid abort()
This method may be invoked at any stage of the processing of the request.
After this method has been invoked, I/O operations on the
streams returned by the getRequestOutputStream
and
getResponseInputStream
methods will fail with an
IOException
, except some operations that may
succeed because they only affect data in local I/O buffers.
If this method is invoked before the close
method has been invoked on the stream returned by
getRequestOutputStream
, there is no guarantee that
any or none of the data written to the stream so far will be
delivered; the implication of such an invocation of this method
is that the user is no longer interested in the successful
delivery of the request.