001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.rest.httppart;
014
015import static org.apache.juneau.httppart.HttpPartType.*;
016
017import java.lang.reflect.*;
018import java.util.regex.*;
019
020import org.apache.http.*;
021import org.apache.juneau.*;
022import org.apache.juneau.http.header.*;
023import org.apache.juneau.http.response.BasicHttpException;
024import org.apache.juneau.httppart.*;
025import org.apache.juneau.rest.*;
026
027/**
028 * Represents a single header on an HTTP request.
029 *
030 * <p>
031 * Typically accessed through the {@link RequestHeaders} class.
032 *
033 * <p>
034 *    Some important methods on this class are:
035 * </p>
036 * <ul class='javatree'>
037 *    <li class='jc'>{@link RequestHeader}
038 *    <ul class='spaced-list'>
039 *       <li>Methods for retrieving simple string values:
040 *       <ul class='javatreec'>
041 *          <li class='jm'>{@link RequestHeader#asString() asString()}
042 *          <li class='jm'>{@link RequestHeader#get() get()}
043 *          <li class='jm'>{@link RequestHeader#isPresent() isPresent()}
044 *          <li class='jm'>{@link RequestHeader#orElse(String) orElse(String)}
045 *       </ul>
046 *       <li>Methods for retrieving as other common types:
047 *       <ul class='javatreec'>
048 *          <li class='jm'>{@link RequestHeader#asBoolean() asBoolean()}
049 *          <li class='jm'>{@link RequestHeader#asBooleanHeader() asBooleanHeader()}
050 *          <li class='jm'>{@link RequestHeader#asCsvArray() asCsvArray()}
051 *          <li class='jm'>{@link RequestHeader#asCsvHeader() asCsvArrayHeader()}
052 *          <li class='jm'>{@link RequestHeader#asDate() asDate()}
053 *          <li class='jm'>{@link RequestHeader#asDateHeader() asDateHeader()}
054 *          <li class='jm'>{@link RequestHeader#asEntityTagsHeader() asEntityTagArrayHeader()}
055 *          <li class='jm'>{@link RequestHeader#asEntityTagHeader() asEntityTagHeader()}
056 *          <li class='jm'>{@link RequestHeader#asInteger() asInteger()}
057 *          <li class='jm'>{@link RequestHeader#asIntegerHeader() asIntegerHeader()}
058 *          <li class='jm'>{@link RequestHeader#asLong() asLong()}
059 *          <li class='jm'>{@link RequestHeader#asLongHeader() asLongHeader()}
060 *          <li class='jm'>{@link RequestHeader#asMatcher(Pattern) asMatcher(Pattern)}
061 *          <li class='jm'>{@link RequestHeader#asMatcher(String) asMatcher(String)}
062 *          <li class='jm'>{@link RequestHeader#asMatcher(String,int) asMatcher(String,int)}
063 *          <li class='jm'>{@link RequestHeader#asStringHeader() asStringHeader()}
064 *          <li class='jm'>{@link RequestHeader#asStringRangesHeader() asStringRangeArrayHeader()}
065 *          <li class='jm'>{@link RequestHeader#asUriHeader() asUriHeader()}
066 *       </ul>
067 *       <li>Methods for retrieving as custom types:
068 *       <ul class='javatreec'>
069 *          <li class='jm'>{@link RequestHeader#as(Class) as(Class)}
070 *          <li class='jm'>{@link RequestHeader#as(ClassMeta) as(ClassMeta)}
071 *          <li class='jm'>{@link RequestHeader#as(Type,Type...) as(Type,Type...)}
072 *          <li class='jm'>{@link RequestHeader#parser(HttpPartParserSession) parser(HttpPartParserSession)}
073 *          <li class='jm'>{@link RequestHeader#schema(HttpPartSchema) schema(HttpPartSchema)}
074 *       </ul>
075 *       <li>Methods for performing assertion checks:
076 *       <ul class='javatreec'>
077 *          <li class='jm'>{@link RequestHeader#assertCsvArray() assertCsvArray()}
078 *          <li class='jm'>{@link RequestHeader#assertDate() assertDate()}
079 *          <li class='jm'>{@link RequestHeader#assertInteger() assertInteger()}
080 *          <li class='jm'>{@link RequestHeader#assertLong() assertLong()}
081 *          <li class='jm'>{@link RequestHeader#assertString() assertString()}
082 *       </ul>
083 *       <li>Other methods:
084 *       <ul class='javatreec'>
085 *          <li class='jm'>{@link RequestHeader#getName() getName()}
086 *          <li class='jm'>{@link RequestHeader#getValue() getValue()}
087*     </ul>
088 * </ul>
089 *
090 * <h5 class='section'>See Also:</h5><ul>
091 *    <li class='link'><a class="doclink" href="../../../../../index.html#jrs.HttpParts">HTTP Parts</a>
092 * </ul>
093 */
094public class RequestHeader extends RequestHttpPart implements Header {
095
096   /**
097    * Constructor.
098    *
099    * @param request The request object.
100    * @param name The header name.
101    * @param value The header value.
102    */
103   public RequestHeader(RestRequest request, String name, String value) {
104      super(HEADER, request, name, value);
105   }
106
107   /**
108    * Returns the value of this header as a {@link BasicCsvHeader}.
109    *
110    * @return The value of this header as a  {@link BasicCsvHeader}, never <jk>null</jk>.
111    */
112   public BasicCsvHeader asCsvHeader() {
113      return new BasicCsvHeader(getName(), getValue());
114   }
115
116   /**
117    * Returns the value of this header as a {@link BasicDateHeader}.
118    *
119    * @return The value of this header as a {@link BasicDateHeader}, never <jk>null</jk>.
120    */
121   public BasicDateHeader asDateHeader() {
122      return new BasicDateHeader(getName(), getValue());
123   }
124
125   /**
126    * Returns the value of this header as a {@link BasicEntityTagsHeader}.
127    *
128    * @return The value of this header as a {@link BasicEntityTagsHeader}, never <jk>null</jk>.
129    */
130   public BasicEntityTagsHeader asEntityTagsHeader() {
131      return new BasicEntityTagsHeader(getName(), getValue());
132   }
133
134   /**
135    * Returns the value of this header as a {@link BasicEntityTagHeader}.
136    *
137    * @return The value of this header as a {@link BasicEntityTagHeader}, never <jk>null</jk>.
138    */
139   public BasicEntityTagHeader asEntityTagHeader() {
140      return new BasicEntityTagHeader(getName(), getValue());
141   }
142
143   /**
144    * Returns the value of this header as a {@link BasicIntegerHeader}.
145    *
146    * @return The value of this header as a {@link BasicIntegerHeader}, never <jk>null</jk>.
147    */
148   public BasicIntegerHeader asIntegerHeader() {
149      return new BasicIntegerHeader(getName(), getValue());
150   }
151
152   /**
153    * Returns the value of this header as a {@link BasicBooleanHeader}.
154    *
155    * @return The value of this header as a {@link BasicBooleanHeader}, never <jk>null</jk>.
156    */
157   public BasicBooleanHeader asBooleanHeader() {
158      return new BasicBooleanHeader(getName(), getValue());
159   }
160
161   /**
162    * Returns the value of this header as a {@link BasicLongHeader}.
163    *
164    * @return The value of this header as a {@link BasicLongHeader}, never <jk>null</jk>.
165    */
166   public BasicLongHeader asLongHeader() {
167      return new BasicLongHeader(getName(), getValue());
168   }
169
170   /**
171    * Returns the value of this header as a {@link BasicStringRangesHeader}.
172    *
173    * @return The value of this header as a {@link BasicStringRangesHeader}, never <jk>null</jk>.
174    */
175   public BasicStringRangesHeader asStringRangesHeader() {
176      return new BasicStringRangesHeader(getName(), getValue());
177   }
178
179   /**
180    * Returns the value of this header as a {@link BasicStringHeader}.
181    *
182    * @return The value of this header as a {@link BasicStringHeader}, never <jk>null</jk>.
183    */
184   public BasicStringHeader asStringHeader() {
185      return new BasicStringHeader(getName(), getValue());
186   }
187
188   /**
189    * Returns the value of this header as a {@link BasicUriHeader}.
190    *
191    * @return The value of this header as a {@link BasicUriHeader}, never <jk>null</jk>.
192    */
193   public BasicUriHeader asUriHeader() {
194      return new BasicUriHeader(getName(), getValue());
195   }
196
197   /**
198    * Parses the value.
199    *
200    * @return An array of {@link HeaderElement} entries, may be empty, but is never <jk>null</jk>.
201    * @throws BasicHttpException In case of a parsing error.
202    */
203   @Override /* Header */
204   public HeaderElement[] getElements() throws BasicHttpException {
205      return new HeaderElement[0];
206   }
207
208   @Override /* Object */
209   public String toString() {
210      return getName() + ": " + getValue();
211   }
212
213   // <FluentSetters>
214
215   @Override /* GENERATED */
216   public RequestHeader schema(HttpPartSchema value) {
217      super.schema(value);
218      return this;
219   }
220
221   @Override /* GENERATED */
222   public RequestHeader parser(HttpPartParserSession value) {
223      super.parser(value);
224      return this;
225   }
226
227   // </FluentSetters>
228}