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.

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 of Payload.Outbound. (The org.glassfish.admin.payload.PayloadImpl.Outbound class is such an implementation.) To this Payload.Outbound object the code can add parts using any of the 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 of Payload.Inbound. (The org.glassfish.admin.payload.PayloadImpl.Inbound is such an implementation.

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
As an example as the server processes the "--retrieve xxx" option on the deploy and redeploy commands it will specify file-xfer-root as xxx (in this example) to indicate where the downloaded app client files should be stored on the local system. Placing such information in the Part's properties helps to decouple the admin client from the specifics of the command which triggered the file transfer. That is, for example, the admin client does not need to fetch the "--retrieve" option value to know where to store the transferred files because the server placed this information with each part. The admin client can therefore process this type of admin data request generically, without regard to what command triggered the transfer.

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

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Payload.Inbound
    Public API for inbound payloads.
    static interface 
    Payload.Outbound
    Public API for outbound Payloads.
    static interface 
    Payload.Part
    Public API for the payload Part.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    PAYLOAD_HEADER_NAME