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