001/* 002 * ==================================================================== 003 * Licensed to the Apache Software Foundation (ASF) under one 004 * or more contributor license agreements. See the NOTICE file 005 * distributed with this work for additional information 006 * regarding copyright ownership. The ASF licenses this file 007 * to you under the Apache License, Version 2.0 (the 008 * "License"); you may not use this file except in compliance 009 * with the License. You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, 014 * software distributed under the License is distributed on an 015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 016 * KIND, either express or implied. See the License for the 017 * specific language governing permissions and limitations 018 * under the License. 019 * ==================================================================== 020 * 021 * This software consists of voluntary contributions made by many 022 * individuals on behalf of the Apache Software Foundation. For more 023 * information on the Apache Software Foundation, please see 024 * <http://www.apache.org/>. 025 * 026 */ 027 028package org.apache.http; 029 030import org.apache.http.params.HttpParams; 031 032/** 033 * HTTP messages consist of requests from client to server and responses 034 * from server to client. 035 * <pre> 036 * HTTP-message = Request | Response ; HTTP/1.1 messages 037 * </pre> 038 * <p> 039 * HTTP messages use the generic message format of RFC 822 for 040 * transferring entities (the payload of the message). Both types 041 * of message consist of a start-line, zero or more header fields 042 * (also known as "headers"), an empty line (i.e., a line with nothing 043 * preceding the CRLF) indicating the end of the header fields, 044 * and possibly a message-body. 045 * </p> 046 * <pre> 047 * generic-message = start-line 048 * *(message-header CRLF) 049 * CRLF 050 * [ message-body ] 051 * start-line = Request-Line | Status-Line 052 * </pre> 053 * 054 * @since 4.0 055 */ 056@SuppressWarnings("deprecation") 057public interface HttpMessage { 058 059 /** 060 * Returns the protocol version this message is compatible with. 061 */ 062 ProtocolVersion getProtocolVersion(); 063 064 /** 065 * Checks if a certain header is present in this message. Header values are 066 * ignored. 067 * 068 * @param name the header name to check for. 069 * @return true if at least one header with this name is present. 070 */ 071 boolean containsHeader(String name); 072 073 /** 074 * Returns all the headers with a specified name of this message. Header values 075 * are ignored. Headers are orderd in the sequence they will be sent over a 076 * connection. 077 * 078 * @param name the name of the headers to return. 079 * @return the headers whose name property equals {@code name}. 080 */ 081 Header[] getHeaders(String name); 082 083 /** 084 * Returns the first header with a specified name of this message. Header 085 * values are ignored. If there is more than one matching header in the 086 * message the first element of {@link #getHeaders(String)} is returned. 087 * If there is no matching header in the message {@code null} is 088 * returned. 089 * 090 * @param name the name of the header to return. 091 * @return the first header whose name property equals {@code name} 092 * or {@code null} if no such header could be found. 093 */ 094 Header getFirstHeader(String name); 095 096 /** 097 * Returns the last header with a specified name of this message. Header values 098 * are ignored. If there is more than one matching header in the message the 099 * last element of {@link #getHeaders(String)} is returned. If there is no 100 * matching header in the message {@code null} is returned. 101 * 102 * @param name the name of the header to return. 103 * @return the last header whose name property equals {@code name}. 104 * or {@code null} if no such header could be found. 105 */ 106 Header getLastHeader(String name); 107 108 /** 109 * Returns all the headers of this message. Headers are orderd in the sequence 110 * they will be sent over a connection. 111 * 112 * @return all the headers of this message 113 */ 114 Header[] getAllHeaders(); 115 116 /** 117 * Adds a header to this message. The header will be appended to the end of 118 * the list. 119 * 120 * @param header the header to append. 121 */ 122 void addHeader(Header header); 123 124 /** 125 * Adds a header to this message. The header will be appended to the end of 126 * the list. 127 * 128 * @param name the name of the header. 129 * @param value the value of the header. 130 */ 131 void addHeader(String name, String value); 132 133 /** 134 * Overwrites the first header with the same name. The new header will be appended to 135 * the end of the list, if no header with the given name can be found. 136 * 137 * @param header the header to set. 138 */ 139 void setHeader(Header header); 140 141 /** 142 * Overwrites the first header with the same name. The new header will be appended to 143 * the end of the list, if no header with the given name can be found. 144 * 145 * @param name the name of the header. 146 * @param value the value of the header. 147 */ 148 void setHeader(String name, String value); 149 150 /** 151 * Overwrites all the headers in the message. 152 * 153 * @param headers the array of headers to set. 154 */ 155 void setHeaders(Header[] headers); 156 157 /** 158 * Removes a header from this message. 159 * 160 * @param header the header to remove. 161 */ 162 void removeHeader(Header header); 163 164 /** 165 * Removes all headers with a certain name from this message. 166 * 167 * @param name The name of the headers to remove. 168 */ 169 void removeHeaders(String name); 170 171 /** 172 * Returns an iterator of all the headers. 173 * 174 * @return Iterator that returns Header objects in the sequence they are 175 * sent over a connection. 176 */ 177 HeaderIterator headerIterator(); 178 179 /** 180 * Returns an iterator of the headers with a given name. 181 * 182 * @param name the name of the headers over which to iterate, or 183 * {@code null} for all headers 184 * 185 * @return Iterator that returns Header objects with the argument name 186 * in the sequence they are sent over a connection. 187 */ 188 HeaderIterator headerIterator(String name); 189 190 /** 191 * Returns the parameters effective for this message as set by 192 * {@link #setParams(HttpParams)}. 193 * 194 * @deprecated (4.3) use configuration classes provided 'org.apache.http.config' 195 * and 'org.apache.http.client.config' 196 */ 197 @Deprecated 198 HttpParams getParams(); 199 200 /** 201 * Provides parameters to be used for the processing of this message. 202 * @param params the parameters 203 * 204 * @deprecated (4.3) use configuration classes provided 'org.apache.http.config' 205 * and 'org.apache.http.client.config' 206 */ 207 @Deprecated 208 void setParams(HttpParams params); 209 210}