{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.

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

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.

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 | ); | }