View Javadoc

    1   /*
    2    * Copyright 2012 The Netty Project
    3    *
    4    * The Netty Project licenses this file to you under the Apache License,
    5    * version 2.0 (the "License"); you may not use this file except in compliance
    6    * with the License. You may obtain a copy of the License at:
    7    *
    8    *   http://www.apache.org/licenses/LICENSE-2.0
    9    *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
    12   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
    13   * License for the specific language governing permissions and limitations
    14   * under the License.
    15   */
    16  package org.jboss.netty.handler.codec.http;
    17
    18  import java.util.List;
    19  import java.util.Map;
    20  import java.util.Set;
    21
    22  import org.jboss.netty.buffer.ChannelBuffer;
    23  import org.jboss.netty.buffer.ChannelBuffers;
    24
    25  /**
    26   * An HTTP message which provides common properties for {@link HttpRequest} and
    27   * {@link HttpResponse}.
    28   * @see HttpHeaders
    29   *
    30   * @apiviz.landmark
    31   * @apiviz.has org.jboss.netty.handler.codec.http.HttpChunk oneway - - is followed by
    32   */
    33  public interface HttpMessage {
    34
    35      /**
    36       * Returns the header value with the specified header name.  If there are
    37       * more than one header value for the specified header name, the first
    38       * value is returned.
    39       *
    40       * @return the header value or {@code null} if there is no such header
    41       */
    42      String getHeader(String name);
    43
    44      /**
    45       * Returns the header values with the specified header name.
    46       *
    47       * @return the {@link List} of header values.  An empty list if there is no
    48       *         such header.
    49       */
    50      List<String> getHeaders(String name);
    51
    52      /**
    53       * Returns the all header names and values that this message contains.
    54       *
    55       * @return the {@link List} of the header name-value pairs.  An empty list
    56       *         if there is no header in this message.
    57       */
    58      List<Map.Entry<String, String>> getHeaders();
    59
    60      /**
    61       * Returns {@code true} if and only if there is a header with the specified
    62       * header name.
    63       */
    64      boolean containsHeader(String name);
    65
    66      /**
    67       * Returns the {@link Set} of all header names that this message contains.
    68       */
    69      Set<String> getHeaderNames();
    70
    71      /**
    72       * Returns the protocol version of this message.
    73       */
    74      HttpVersion getProtocolVersion();
    75
    76      /**
    77       * Sets the protocol version of this message.
    78       */
    79      void setProtocolVersion(HttpVersion version);
    80
    81      /**
    82       * Returns the content of this message.  If there is no content or
    83       * {@link #isChunked()} returns {@code true}, an
    84       * {@link ChannelBuffers#EMPTY_BUFFER} is returned.
    85       */
    86      ChannelBuffer getContent();
    87
    88      /**
    89       * Sets the content of this message.  If {@code null} is specified,
    90       * the content of this message will be set to {@link ChannelBuffers#EMPTY_BUFFER}.
    91       */
    92      void setContent(ChannelBuffer content);
    93
    94      /**
    95       * Adds a new header with the specified name and value.
    96       */
    97      void addHeader(String name, Object value);
    98
    99      /**
    100      * Sets a new header with the specified name and value.  If there is an
    101      * existing header with the same name, the existing header is removed.
    102      */
    103     void setHeader(String name, Object value);
    104
    105     /**
    106      * Sets a new header with the specified name and values.  If there is an
    107      * existing header with the same name, the existing header is removed.
    108      */
    109     void setHeader(String name, Iterable<?> values);
    110
    111     /**
    112      * Removes the header with the specified name.
    113      */
    114     void removeHeader(String name);
    115
    116     /**
    117      * Removes all headers from this message.
    118      */
    119     void clearHeaders();
    120
    121     /**
    122      * @deprecated Use {@link HttpHeaders#getContentLength(HttpMessage)} instead.
    123      */
    124     @Deprecated
    125     long getContentLength();
    126
    127     /**
    128      * @deprecated Use {@link HttpHeaders#getContentLength(HttpMessage, long)} instead.
    129      */
    130     @Deprecated
    131     long getContentLength(long defaultValue);
    132
    133     /**
    134      * Returns {@code true} if and only if this message does not have any
    135      * content but the {@link HttpChunk}s, which is generated by
    136      * {@link HttpMessageDecoder} consecutively, contain the actual content.
    137      * <p>
    138      * Please note that this method will keep returning {@code true} if the
    139      * {@code "Transfer-Encoding"} of this message is {@code "chunked"}, even if
    140      * you attempt to override this property by calling {@link #setChunked(boolean)}
    141      * with {@code false}.
    142      */
    143     boolean isChunked();
    144
    145     /**
    146      * Sets if this message does not have any content but the
    147      * {@link HttpChunk}s, which is generated by {@link HttpMessageDecoder}
    148      * consecutively, contain the actual content.
    149      * <p>
    150      * If this method is called with {@code true}, the content of this message
    151      * becomes {@link ChannelBuffers#EMPTY_BUFFER}.
    152      * <p>
    153      * Even if this method is called with {@code false}, {@link #isChunked()}
    154      * will keep returning {@code true} if the {@code "Transfer-Encoding"} of
    155      * this message is {@code "chunked"}.
    156      */
    157     void setChunked(boolean chunked);
    158
    159     /**
    160      * @deprecated Use {@link HttpHeaders#isKeepAlive(HttpMessage)} instead.
    161      */
    162     @Deprecated
    163     boolean isKeepAlive();
    164 }