001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2009 Sun Microsystems Inc.
015 * Portions Copyright 2010–2011 ApexIdentity Inc.
016 * Portions Copyright 2011-2015 ForgeRock AS.
017 */
018
019package org.forgerock.http.protocol;
020
021import java.io.Closeable;
022
023/**
024 * Elements common to requests and responses.
025 */
026public interface Message extends Closeable {
027
028    /**
029     * Returns the entity.
030     *
031     * @return The entity.
032     */
033    Entity getEntity();
034
035    /**
036     * Returns the headers.
037     *
038     * @return The headers.
039     */
040    Headers getHeaders();
041
042    /**
043     * Returns the protocol version. Default: {@code HTTP/1.1}.
044     *
045     * @return The protocol version.
046     */
047    String getVersion();
048
049    /**
050     * Sets the content of the entity to the provided value. Calling this method
051     * will close any existing streams associated with the entity. May also set
052     * the {@code Content-Length} header, overwriting any existing header.
053     * <p>
054     * This method is intended mostly as a convenience method within scripts.
055     * The parameter will be handled depending on its type as follows:
056     * <ul>
057     * <li>{@code BranchingInputStream} - equivalent to calling
058     * {@link Entity#setRawContentInputStream}
059     * <li>{@code byte[]} - equivalent to calling {@link Entity#setBytes}
060     * <li>{@code String} - equivalent to calling {@link Entity#setString}
061     * <li>{@code Object} - equivalent to calling {@link Entity#setJson}.
062     * </ul>
063     * <p>
064     * Note: This method does not attempt to encode the entity based-on any
065     * codings specified in the {@code Content-Encoding} header.
066     *
067     * @param o
068     *            The object whose value should be stored in the entity.
069     * @return This message.
070     */
071    Message setEntity(Object o);
072
073    /**
074     * Sets the protocol version. Default: {@code HTTP/1.1}.
075     *
076     * @param version
077     *            The protocol version.
078     * @return This message.
079     */
080    Message setVersion(final String version);
081
082    /**
083     * Closes all resources associated with the entity. Any open streams will be
084     * closed, and the underlying content reset back to a zero length.
085     *
086     * @see Entity#close()
087     */
088    @Override
089    void close();
090}