Helper Classes

The org.apache.juneau.http.header package contains various convenience classes for creating standard HTTP components using static imports.

HttpHeaders - Utility class for standard HTTP headers.HttpParts - Utility class for standard HTTP parts.HttpEntities - Utility class for standard HTTP entities.HttpResources - Utility class for standard HTTP resources.HttpResponses - Utility class for standard HTTP responses.

HttpHeaders

info

There are two HttpHeaders classes: the transport-neutral NG org.apache.juneau.http.HttpHeaders (strongly-typed creators only, e.g. accept(String), contentType(String); see HTTP Headers) and the classic org.apache.juneau.http.classic.HttpHeaders documented below, which adds free-form header creators and HeaderList builders on top of the Apache HttpCore-based header types.

The HttpHeaders class contains many convenience static methods and fields for working with standard HTTP request and response headers and header lists.

Example

import static org.apache.juneau.http.classic.HttpHeaders.*;

HeaderList headers =
    headerList(  // Arbitrary list of headers
        CONTENTTYPE_TEXT_XML,   // Static constants
        contentType("text/xml"),   // Predefined headers
        contentType(() -> "text/xml"),   // Predefined headers with supplied values
        stringHeader("Content-Type", "text/xml"),   // Freeform headers
        stringHeader("Content-Type", () -> "text/xml")   // Freeform headers with supplied values
    );

This class is vast in scope and covers all request and response headers defined in RFC2616. In addition to the predefined headers, various methods are provided for free-form headers. Each accepts either static values or values from Suppliers:

HttpHeadersbasicHeader(String,Object)booleanHeader(String,String)csvHeader(String,String)dateHeader(String,String)entityTagsHeader(String,String)entityTagHeader(String,String)integerHeader(String,String)longHeader(String,String)mediaRangesHeader(String,String)mediaTypeHeader(String,String)stringHeader(String,String)serializedHeader(String,Object)stringRangesHeader(String,String)uriHeader(String,String)

The serializedHeader methods allows for headers serialized using schema-based serializers such as the OpenAPI serializer.

Static methods are also provided for instantiating Header-annotated or other HttpComponent-defined header classes:

HttpHeadersheader(Class,String,Object)header(Class,Object)

Example

import static org.apache.juneau.http.classic.HttpHeaders.*;

ContentType contentType = header(ContentType.class, "text/xml");

Lists of headers can be produced with the following methods:

HttpHeadersheaderList()headerList(Header...)headerList(List)headerList(String...)

The capabilities of the HeaderList class is described later.

HttpParts

info

There are two HttpParts classes: the transport-neutral NG org.apache.juneau.http.HttpParts (minimal surface: part(String,String), partList(HttpPart...), partListOfPairs(String...)) and the classic org.apache.juneau.http.classic.HttpParts documented below, which adds typed free-form part creators on top of the Apache HttpCore-based NameValuePair types.

The HttpParts class contains convenience static methods for generating query/form-data/path parts and part lists.

Example

import static org.apache.juneau.http.classic.HttpParts.*;

PartList formData =
    partList(  // Arbitrary list of parts
        stringPart("Name", "Bill"),   // Freeform part
        integerPart("Age", () -> calculateAge())   // Freeform part with supplied value
    );

The following methods are provided for creating parts. Each accepts either static values or values from Suppliers:

HttpPartsbasicPart(String,Object)booleanPart(String,Boolean)csvArrayPart(String,String...)datePart(String,ZonedDateTime)integerPart(String,Integer)longPart(String,Long)serializedPart(String,Object)stringPart(String,String)uriPart(String,URI)

The serializedPart methods allows for parts serialized using schema-based serializers such as the OpenAPI serializer.

Lists of parts can be produced with the following methods:

HttpPartspartList()partList(List)partList(NameValuePair...)partList(String...)

The capabilities of the PartList class is described later.

HttpEntities

The HttpEntities class contains convenience static methods for generating HTTP message entities.

Returned objects extend from org.apache.http.HttpEntity but provides the following additional features:

• Caching.
• Fluent setters.
• Fluent assertions.
• Externally-supplied/dynamic content.

The following methods are provided for creating entities. Each accepts either static values or values from Suppliers and returns builders:

HttpEntitiesbyteArrayEntity(byte[])fileEntity(File)readerEntity(Reader)serializedEntity(Object, Serializer)streamEntity(InputStream)stringEntity(String)

HTTP entities are automatically supported in both the server and client REST APIs for requests and responses.

Example

import static org.apache.juneau.http.classic.HttpEntities.*;

@RestDelete(path="/{id}")
public HttpEntity helloWold(...) {
    return stringEntity("Hello!").contentType("text/plain");
}

HttpResources

The HttpResources class contains convenience static methods for generating HTTP message resources. Returned objects extend from HttpResource which extends from HttpEntity but with additional arbitrary headers.

The following methods are provided for creating entities. Each accepts either static values or values from Suppliers and are in the form of builders.

HttpResourcesbyteArrayResource(byte[])fileResource(File)readerResource(Reader)streamResource(InputStream)stringResource(String)

The most common location where resources are used are as returned types of REST operation methods described later.

Example

import static org.apache.juneau.http.classic.HttpResources.*;

@RestDelete(path="/{id}")
public HttpResource helloWold(...) {
    return stringResource("Hello!").contentType("text/plain").header("Cache-Control", "none");
}

HttpResponses

The HttpResponses class contains convenience static methods for standard HTTP responses. Returned objects implement the transport-neutral HttpResponseMessage interface (which mirrors org.apache.http.HttpResponse semantics without the Apache HttpCore dependency) and are in the form of builders. The following methods are provided for creating responses:

HttpResponses _continue accepted alreadyReported badRequest conflict created earlyHints expectationFailed failedDependency forbidden found gone httpVersionNotSupported imUsed insufficientStorage internalServerError lengthRequired locked loopDetected methodNotAllowed misdirectedRequest movedPermanently multipleChoices multiStatus networkAuthenticationRequired noContent nonAuthoritiveInformation notAcceptable notExtended notFound notImplemented notModified ok partialContent payloadTooLarge permanentRedirect preconditionFailed preconditionRequired processing rangeNotSatisfiable requestHeaderFieldsTooLarge resetContent seeOther serviceUnavailable switchingProtocols temporaryRedirect tooManyRequests unauthorized unavailableForLegalReasons unprocessableEntity unsupportedMediaType upgradeRequired uriTooLong useProxy variantAlsoNegotiates

The most common location where these responses are used are in REST operation methods described later.

Example

import static org.apache.juneau.http.HttpResponses.*;
import static org.apache.juneau.http.HttpHeaders.*;

@RestDelete(path="/{id}")
public Ok doDelete(...) throws Unauthorized {
    if (/* user not authorized*/)
        throw unauthorized();
    return ok().content("Delete was successful");
}