Package org.glassfish.api.admin
Interface Payload
public interface Payload
Interface for admin command payloads--data carried in the http request and response which flow between the admin
client and the server. This API also allows the requester to ask that the receiver remove a file, presumably one that
was transferred via an earlier request payload.
class is such an implementation.) To this Payload.Outbound
object the code can add parts using any of the
is such an implementation.
Motivation and Overview
The API is intended to be a simple abstraction of the input and output streams in HTTP requests and responses, inspired by the concepts from the mail API for MIME body parts and multiparts. A payload can contain zero or more parts. If a payload contains only one part then only that part is sent or received in the payload. If, on the other hand, the payload contains multiple parts then the payload as a whole is a "multipart" payload which in turn contains the individual parts.Usage
Outbound
Code (on the client or the server) that needs to place data in the payload or request that earlier-sent data be removed would instantiate an implementation ofPayload.Outbound
. (The
invalid reference
org.glassfish.admin.payload.PayloadImpl.Outbound
Payload.Outbound.addPart(java.lang.String, java.lang.String, java.util.Properties, java.lang.String)
methods or the Payload.Outbound.attachFile(java.lang.String, java.net.URI, java.lang.String, java.io.File)
or
Payload.Outbound.requestFileRemoval(java.net.URI, java.lang.String, java.util.Properties)
convenience methods. After the code has added all the relevant parts to the
payload it invokes the Payload.Outbound.writeTo(java.io.OutputStream)
method to write the outbound payload to an OutputStream. Typically
the caller will pass the output stream associated with the request (in the client case) or the response (in the
server case).
Inbound
Code that needs to read the payload from a request (as the server does) or from a response (as the client does) will instantiate an implementation ofPayload.Inbound
. (The
invalid reference
org.glassfish.admin.payload.PayloadImpl.Inbound
Payload.Inbound exposes the Payload.Inbound.parts()
method which returns an Iterator<Part>. With each
Payload.Part
available through the iterator the caller can use Payload.Part.getContentType()
, Payload.Part.getName()
,
and Payload.Part.getInputStream()
. Note that the caller should close the InputStream returned by getInputStream()
once it has read the data from the stream.
Part Properties
Each Part can carry with it Properties. The conventions as to what property names are used and what they mean can vary from one admin command to the next. For a file transfer these properties should be set:- data-request-type=file-xfer
- data-request-name=(anything - typically the option name from the command to help identify which part goes with which command argument)
- file-xfer-root=root path expression in the file system syntax of the system where tranferred files will reside.
- last-modified=String representation of the long value recording the last-modified time of the original file
The receiver of the file transfer request should return the file-xfer-root value back to the requester without change so the local file path syntax can be used correctly on the system where the file will exist.
Notes and Restrictions
In some implementations the caller must consume the contents of a Part's input stream before advancing to the next Part. All callers should follow this practice regardless of the underlying implementation used, in case that implementation were to change in the future.- Author:
- tjquinn
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic interface
Public API for inbound payloads.static interface
Public API for outbound Payloads.static interface
Public API for the payload Part. -
Field Summary
-
Field Details
-
PAYLOAD_HEADER_NAME
- See Also:
-