Glassfish example source code file (Payload.java)

This example Glassfish source code file (Payload.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Java - Glassfish tags/keywords

file, inbound, inputstream, io, ioexception, ioexception, iterator, net, network, outputstream, part, properties, properties, string, string, uri, uri, util

The Glassfish Payload.java source code

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
 *
 * The contents of this file are subject to the terms of either the GNU
 * General Public License Version 2 only ("GPL") or the Common Development
 * and Distribution License("CDDL") (collectively, the "License").  You
 * may not use this file except in compliance with the License.  You can
 * obtain a copy of the License at
 * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
 * or packager/legal/LICENSE.txt.  See the License for the specific
 * language governing permissions and limitations under the License.
 *
 * When distributing the software, include this License Header Notice in each
 * file and include the License file at packager/legal/LICENSE.txt.
 *
 * GPL Classpath Exception:
 * Oracle designates this particular file as subject to the "Classpath"
 * exception as provided by Oracle in the GPL Version 2 section of the License
 * file that accompanied this code.
 *
 * Modifications:
 * If applicable, add the following below the License Header, with the fields
 * enclosed by brackets [] replaced by your own identifying information:
 * "Portions Copyright [year] [name of copyright owner]"
 *
 * Contributor(s):
 * If you wish your version of this file to be governed by only the CDDL or
 * only the GPL Version 2, indicate your decision by adding "[Contributor]
 * elects to include this software in this distribution under the [CDDL or GPL
 * Version 2] license."  If you don't indicate a single choice of license, a
 * recipient has the option to distribute your version of this file under
 * either the CDDL, the GPL Version 2 or to extend the choice of license to
 * its licensees as provided above.  However, if you add GPL Version 2 code
 * and therefore, elected the GPL Version 2 license, then the option applies
 * only if the new code is made subject to such option by the copyright
 * holder.
 */

package org.glassfish.api.admin;

import java.io.ByteArrayInputStream;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import java.net.URI;
import java.util.Iterator;
import java.util.Properties;

/**
 * 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.
 * <h2>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.
 * <h2>Usage
 * <h3>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 {@link Payload.Outbound}. (The
 * {@link 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 {@link Outbound#addPart}
 * methods or the {@link Outbound#attachFile} or {@link Outbound#requestFileRemoval} convenience methods.
 * After the code has added all
 * the relevant parts to the payload it invokes the {@link Outbound#writeTo} 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).
 * <h3>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
 * {@link Payload.Inbound}. (The {@link org.glassfish.admin.payload.PayloadImpl.Inbound}
 * is such an implementation.
 * <p>
 * Payload.Inbound exposes the {@link Payload.Inbound#parts()} method
 * which returns an Iterator<Part>.  With each {@link Part} available through the
 * iterator the caller can use {@link Part#getContentType()},
 * {@link Part#getName()}, and {@link Part#getInputStream()}.
 * Note that the caller should close the InputStream returned by getInputStream()
 * once it has read the data from the stream.
 * <h2>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:
 * <ul>
 * <li>data-request-type=file-xfer
 * <li>data-request-name=(anything - typically the option name from the command to
 * help identify which part goes with which command argument)
 * <li>file-xfer-root=root path expression in the file system syntax of the system
 * where tranferred files will reside.
 * <li>last-modified=String representation of the long value recording the last-modified time of the original file
 * </ul>
 * 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.
 * <p>
 * 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.  
 * <h2>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
 */
public interface Payload {

    public static final String PAYLOAD_HEADER_NAME = "org.glassfish.payload.admin.data";

    /**
     * Public API for outbound Payloads.
     */
    public static interface Outbound {

        /**
         * Adds a part of the specified content type, name, and String content
         * to the payload.
         * @param contentType content type of the part
         * @param name name to be assigned to the part
         * @param props Properties to be included with the part
         * @param content String containing the content for the part
         * @throws java.io.IOException
         */
        public void addPart(
                final String contentType,
                final String name,
                final Properties props,
                final String content) throws IOException;

        /**
         * Adds a part of the specified content type, name, and content to
         * the payload.
         * @param contentType content type of the part
         * @param name name to be assigned to the part
         * @param props Properties to be included with the part
         * @param content InputStream furnishing the content for this part
         * @throws java.io.IOException
         */
        public void addPart(
                final String contentType,
                final String name,
                final Properties props,
                final InputStream content) throws IOException;

        /**
         * Adds a part of the specified content type, name, and content at a
         * specified position in the parts of the payload.
         * @param index position (zero-based) where the part should be added
         * @param contentType content type of the part
         * @param name name to be assigned to thepart
         * @param props Properties to be included with the part
         * @param content InputStream furnishing the content for this part
         * @throws java.io.IOException
         */
        public void addPart(
                final int index,
                final String contentType,
                final String name,
                final Properties props,
                final InputStream content
                ) throws IOException;

        /**
         * Adds a part to the payload of the given content type from the
         * specified file.  The name assigned to the new part is the URI
         * for the file relativized according to the specified file URI.  The
         * properties which indicate that this is file transfer data request
         * are set automatically.
         * @param contentType content type of the part
         * @param fileURI URI relative to which the part's name should be computed
         * @param dataRequestName name identifying which part of a request this file answers
         * @param file File containing the content for the part
         * @throws java.io.IOException
         */
        public void attachFile(
                final String contentType,
                final URI fileURI,
                final String dataRequestName,
                final File file) throws IOException;

        /**
         * Adds a part to the payload of the given content type from the
         * specified file.  The name assigned to the new part is the URI
         * for the file relativized according to the specified file URI.  The
         * properties which indicate that this is file transfer data request
         * are set automatically.
         * @param contentType content type of the part
         * @param fileURI URI relative to which the part's name should be computed
         * @param dataRequestName name identifying which part of a request this file answers
         * @param file File containing the content for the part
         * @param isRecursive if file is a directory, whether to add its contents as well
         * @throws java.io.IOException
         */
        public void attachFile(
                final String contentType,
                final URI fileURI,
                final String dataRequestName,
                final File file,
                final boolean isRecursive) throws IOException;

        /**
         * Adds a part to the payload of the given content type from the
         * specified file.  The name assigned to the new part is the URI
         * for the file relativized according to the specified file URI.  The
         * properties which indicate that this is a file transfer data request
         * are set automatically and added to the properties passed by the caller.
         * @param contentType content type of the part
         * @param fileURI URI relative to which the part's name should be computed
         * @param dataRequestName name identifying which part of a request this file answers
         * @param props Properties to be included with the part
         * @param file File containing the content for the part
         * @throws java.io.IOException
         */
        public void attachFile(
                final String contentType,
                final URI fileURI,
                final String dataRequestName,
                final Properties props,
                final File file) throws IOException;

        /**
         * Adds a part to the payload of the given content type from the
         * specified file.  The name assigned to the new part is the URI
         * for the file relativized according to the specified file URI.  The
         * properties which indicate that this is a file transfer data request
         * are set automatically and added to the properties passed by the caller.
         * @param contentType content type of the part
         * @param fileURI URI relative to which the part's name should be computed
         * @param dataRequestName name identifying which part of a request this file answers
         * @param props Properties to be included with the part
         * @param file File containing the content for the part
         * @param isRecursive if file is a directory, whether to add its contents as well
         * @throws java.io.IOException
         */
        public void attachFile(
                final String contentType,
                final URI fileURI,
                final String dataRequestName,
                final Properties props,
                final File file,
                final boolean isRecursive) throws IOException;

        /**
         * Adds a part to the payload that represents a request to remove the
         * specified file, presumably previously transferred in a payload
         * during an earlier request.
         * @param fileURI relative URI of the file for deletion
         * @param dataRequestName name identifying which part of a request triggered the file removal
         * @param props Properties to be included with the part
         * @throws IOException
         */
        public void requestFileRemoval(
                final URI fileURI,
                final String dataRequestName,
                final Properties props) throws IOException;

        /**
         * Adds a part to the payload that represents a request to remove the
         * specified file, presumably previously transferred in a payload
         * during an earlier request.
         * @param fileURI relative URI of the file for deletion
         * @param dataRequestName name identifying which part of a request triggered the file removal
         * @param props Properties to be included with the part
         * @param isRecursive if fileURI is a directory, whether to remove its contents as well
         * @throws IOException
         */
        public void requestFileRemoval(
                final URI fileURI,
                final String dataRequestName,
                final Properties props,
                final boolean isRecursive) throws IOException;

        /**
         * Adds a part to the payload to request that the specified file be
         * replaced.  
         * <p>
         * If the fileURI translates to a non-directory file on the receiving
         * system then calling this method will replace the file's contents
         * on the target with the contents of the <code>file argument.
         * <p>
         * If the fileURI is for a directory, then if isRecursive is also 
         * specified the payload will contain one Part to replace the 
         * directory (which will have the result of removing the directory
         * and its contents and then recreating the directory) plus a Part for
         * each file, including subdirectories, below the directory.  The
         * intent is to replace the entire directory with new contents.  
         * @param fileURI
         * @param dataRequestName
         * @param props
         * @param isRecursive
         * @throws IOException
         */
        public void requestFileReplacement(
                final String contentType,
                final URI fileURI,
                final String dataRequestName,
                final Properties props,
                final File file,
                final boolean isRecursive) throws IOException;

        /**
         * Writes the parts already added to the payload to the specified
         * OutputStream.
         * @param os OutputStream to receive the formatted payload
         * @throws java.io.IOException
         */
        public void writeTo(final OutputStream os) throws IOException;

        /**
         * Returns the content type of the payload, determined by whether there
         * are multiple parts and, if not, if the content type of the single
         * part is of type "text."
         * @return the content type of the pauload
         */
        public String getContentType();

        /**
         * Returns the name of the header that should be set in the outgoing and
         * incoming http request or response.
         * @return the header name
         */
        public String getHeaderName();

    }

    /**
     * Public API for inbound payloads.
     */
    public static interface Inbound {

        /**
         * Returns the parts from the inbound payload.
         * @return Iterator over the inbound Parts
         */
        public Iterator<Part> parts();

        /**
         * Returns the name of the header that should be set in the outgoing and
         * incoming http request or response.
         * @return the header name
         */
        public String getHeaderName();


    }

    /**
     * Public API for the payload Part.
     */
    public static interface Part {

        /**
         * Returns the name assigned to the part when it was created.
         * @return name
         */
        public String getName();

        /**
         * Returns the content type of the part.
         * @return content type
         */
        public String getContentType();

        /**
         * Returns the Properties associated with the Part.
         * @return Properties for the Part
         */
        public Properties getProperties();

        /**
         * Returns an InputStream suitable for reading the content of the Part.
         * @return
         */
        public InputStream getInputStream();

        /**
         * Copies the contents of the Part to the specified OutputStream.
         * @param os target OutputStream to receive the content of the Part
         * @throws java.io.IOException
         */
        public void copy(final OutputStream os) throws IOException;

        /**
         * Indicates if the Part represents a recursive action or not.
         * @return
         */
        public boolean isRecursive();

    }
}