{title:'HTTP Headers', created:'9.0.0'}

The {@link oaj.http.header} package contains implementations of org.apache.http.Header for all common HTTP headers.

- {@link oaj.http.header.Accept}
- {@link oaj.http.header.AcceptCharset}
- {@link oaj.http.header.AcceptEncoding}
- {@link oaj.http.header.AcceptLanguage}
- {@link oaj.http.header.AcceptRanges}
- {@link oaj.http.header.Age}
- {@link oaj.http.header.Allow}
- {@link oaj.http.header.Authorization}
- {@link oaj.http.header.CacheControl}
- {@link oaj.http.header.ClientVersion}
- {@link oaj.http.header.Connection}
- {@link oaj.http.header.ContentDisposition}
- {@link oaj.http.header.ContentEncoding}
- {@link oaj.http.header.ContentLanguage}
- {@link oaj.http.header.ContentLength}
- {@link oaj.http.header.ContentLocation}
- {@link oaj.http.header.ContentRange}
- {@link oaj.http.header.ContentType}
- {@link oaj.http.header.Date}
- {@link oaj.http.header.Debug}
- {@link oaj.http.header.ETag}
- {@link oaj.http.header.Expect}
- {@link oaj.http.header.Expires}
- {@link oaj.http.header.Forwarded}
- {@link oaj.http.header.From}
- {@link oaj.http.header.Host}
- {@link oaj.http.header.IfMatch}
- {@link oaj.http.header.IfModifiedSince}
- {@link oaj.http.header.IfNoneMatch}
- {@link oaj.http.header.IfRange}
- {@link oaj.http.header.IfUnmodifiedSince}
- {@link oaj.http.header.LastModified}
- {@link oaj.http.header.Location}
- {@link oaj.http.header.MaxForwards}
- {@link oaj.http.header.NoTrace}
- {@link oaj.http.header.Origin}
- {@link oaj.http.header.Pragma}
- {@link oaj.http.header.ProxyAuthenticate}
- {@link oaj.http.header.ProxyAuthorization}
- {@link oaj.http.header.Range}
- {@link oaj.http.header.Referer}
- {@link oaj.http.header.RetryAfter}
- {@link oaj.http.header.Server}
- {@link oaj.http.header.TE}
- {@link oaj.http.header.Thrown}
- {@link oaj.http.header.Trailer}
- {@link oaj.http.header.TransferEncoding}
- {@link oaj.http.header.Upgrade}
- {@link oaj.http.header.UserAgent}
- {@link oaj.http.header.Vary}
- {@link oaj.http.header.Via}
- {@link oaj.http.header.Warning}
- {@link oaj.http.header.WwwAuthenticate}

These headers extend from the following classes that provide data-type specific functionality:

- {@code org.apache.http.NameValuePair}
  - {@code org.apache.http.Header}
    - {@link oaj.http.header.BasicHeader}
      - {@link oaj.http.header.BasicBooleanHeader}
      - {@link oaj.http.header.BasicCsvHeader}
      - {@link oaj.http.header.BasicDateHeader}
      - {@link oaj.http.header.BasicEntityTagHeader}
      - {@link oaj.http.header.BasicEntityTagsHeader}
      - {@link oaj.http.header.BasicIntegerHeader}
      - {@link oaj.http.header.BasicLongHeader}
      - {@link oaj.http.header.BasicMediaRangesHeader}
      - {@link oaj.http.header.BasicMediaTypeHeader}
      - {@link oaj.http.header.BasicStringHeader}
      - {@link oaj.http.header.BasicStringRangesHeader}
      - {@link oaj.http.header.BasicUriHeader}

These subclasses provide various convenience methods to allow for easy fluent-style coding.

##### Examples

| // Validates the response body content is not expired. | restClient | .get(URL) | .run() | .getHeader("Expires").asDateHeader().assertZonedDateTime().isLessThan(new Date());

##### HeaderList

The {@link oaj.http.header.HeaderList} class is a list of HTTP headers.

##### Example

| // Construct using builder. | HeaderList headers = HeaderList | .create() | .append(Accept.of("text/xml")) | .append("Content-Type", ()->getDynamicContentTypeFromSomewhere()); | | // Construct using convenience creator. | HeaderList headers = HeaderList.of(Accept.TEXT_XML, ContentType.TEXT_XML);

Static methods are provided on {@link oaj.http.HttpHeaders} to further simplify creation of header lists.

| import static org.apache.juneau.http.HttpHeaders.*; | | HeaderList headers = headerList(accept("text/xml"), contentType("text/xml"));

The builder class supports setting default header values (i.e. add a header to the list if it isn't otherwise in the list). Note that this is different from simply setting a value twice as using default values will not overwrite existing headers.
The following example notes the distinction:

| headers = HeaderList | .create() | .set(Accept.TEXT_PLAIN) | .set(Accept.TEXT_XML); | assertObject(headers).isString("[Accept: text/xml]"); | | headers = HeaderList | .create() | .set(Accept.TEXT_PLAIN) | .setDefault(Accept.TEXT_XML); | assertObject(headers).isString("[Accept: text/plain]");

Various methods are provided for iterating over the headers in this list to avoid array copies.

- {@link oaj.http.header.HeaderList#forEach(Consumer) forEach(Consumer)} / {@link oaj.http.header.HeaderList#forEach(String,Consumer) forEach(String,Consumer)} / {@link oaj.http.header.HeaderList#forEach(Predicate,Consumer) forEach(Predicate,Consumer)} - Use consumers to process headers.
- {@link oaj.http.header.HeaderList#headerIterator() headerIterator()} / {@link oaj.http.header.HeaderList#headerIterator(String) headerIterator(String)} - Use an {@link org.apache.http.HeaderIterator} to process headers.
- {@link oaj.http.header.HeaderList#stream() stream()} / {@link oaj.http.header.HeaderList#stream(String) stream(String)} - Use a stream.

In general, try to use these over the {@link oaj.http.header.HeaderList#getAll() getAll()} / {@link oaj.http.header.HeaderList#getAll(String) getAll(String)} methods that require array copies.

The {@link oaj.http.header.HeaderList#get(String) get(String)} method is special in that it will collapse multiple headers with the same name into a single comma-delimited list (see RFC 2616 Section 4.2 for rules).

The {@link oaj.http.header.HeaderList#get(Class) get(Class)} and {@link oaj.http.header.HeaderList#get(String,Class) get(String,Class)} methods are provided for working with {@link oaj.http.annotation.Header}-annotated beans.

##### Example

| HeaderList headers = HeaderList.of(Accept.TEXT_JSON, Accept.TEXT_XML); | | // Returns "text/json, text/xml" | Accept accept = headers.get(Accept.class);

By default, header names are treated as case-insensitive. This can be changed using the {@link oaj.http.header.HeaderList#caseSensitive(boolean) caseSensitive(boolean)} method.

A {@link oaj.svl.VarResolver} can be associated with this builder to create header values with embedded variables that are resolved at runtime.

##### Example

| // Create a header list with dynamically-resolving values pulled from a system property. | | System.setProperty("foo", "bar"); | | HeaderList headers = HeaderList | .create() | .resolving() | .append("X1", "$S{foo}") | .append("X2", ()->"$S{foo}"); | | assertObject(headers).isString("[X1: bar, X2: bar]");

The {@link oaj.http.header.HeaderList} object can be extended to defined pre-packaged lists of headers which can be used in various annotations throughout the framework.

##### Example

| // A predefined list of headers. | public class MyHeaderList extends HeaderList { | public MyHeaderList() { | super(Accept.TEXT_XML, ContentType.TEXT_XML); | } | } | | // Use it on a remote proxy to add headers on all requests. | @Remote(path="/petstore", headerList=MyHeaderList.class) | public interface PetStore { | | @RemotePost("/pets") | Pet addPet( | @Content CreatePet createPet, | @Header("E-Tag") UUID etag, | @Query("debug") boolean debug | ); | }