Skip to main content

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

HttpHeaders​

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

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

Example
import static org.apache.juneau.http.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.HttpResources.*;

@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.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 extend from org.apache.http.HttpResponse and are in the form of builders. The following methods are provided for creating entities:

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