tessl/maven-com-squareup-okhttp--okhttp
An HTTP & SPDY client for Android and Java applications with efficient connection pooling, interceptors, and modern protocol support
—
Pending
request-building.mddocs/
Request Building
Fluent API for building HTTP requests with URLs, methods, headers, and request bodies. Requests are immutable once built.
Capabilities
Request
Immutable HTTP request with URL, method, headers, and optional body.
/**
* An HTTP request. Instances of this class are immutable if their body
* is null or itself immutable.
*/
public final class Request {
public HttpUrl httpUrl();
public URL url();
public URI uri() throws IOException;
public String urlString();
public String method();
public Headers headers();
public String header(String name);
public List<String> headers(String name);
public RequestBody body();
public Object tag();
public Builder newBuilder();
public CacheControl cacheControl();
public boolean isHttps();
}Request.Builder
Builder for constructing Request objects with fluent API.
/**
* Builder for constructing Request objects.
*/
public static class Builder {
public Builder();
public Builder url(HttpUrl url);
public Builder url(String url);
public Builder url(URL url);
public Builder header(String name, String value);
public Builder addHeader(String name, String value);
public Builder removeHeader(String name);
public Builder headers(Headers headers);
public Builder cacheControl(CacheControl cacheControl);
public Builder get();
public Builder head();
public Builder post(RequestBody body);
public Builder delete(RequestBody body);
public Builder delete();
public Builder put(RequestBody body);
public Builder patch(RequestBody body);
public Builder method(String method, RequestBody body);
public Builder tag(Object tag);
public Request build();
}Basic Usage:
// Simple GET request
Request request = new Request.Builder()
.url("https://api.example.com/users")
.build();
// POST request with JSON body
RequestBody body = RequestBody.create(
MediaType.parse("application/json"),
"{\"name\":\"John\",\"email\":\"john@example.com\"}"
);
Request request = new Request.Builder()
.url("https://api.example.com/users")
.post(body)
.build();URL Configuration
Set the target URL for the HTTP request using various URL types.
/**
* Sets the URL target of this request.
* @param url the HttpUrl to use
* @return this builder for method chaining
*/
public Builder url(HttpUrl url);
/**
* Sets the URL target of this request.
* @param url the URL string to parse and use
* @return this builder for method chaining
* @throws IllegalArgumentException if url is not a valid HTTP or HTTPS URL
*/
public Builder url(String url);
/**
* Sets the URL target of this request.
* @param url the java.net.URL to convert and use
* @return this builder for method chaining
* @throws IllegalArgumentException if the scheme is not http or https
*/
public Builder url(URL url);Usage Examples:
// From string
Request request = new Request.Builder()
.url("https://api.example.com/users?page=1")
.build();
// From HttpUrl (with building)
HttpUrl url = HttpUrl.parse("https://api.example.com")
.newBuilder()
.addPathSegment("users")
.addQueryParameter("page", "1")
.build();
Request request = new Request.Builder()
.url(url)
.build();
// From java.net.URL
URL javaUrl = new URL("https://api.example.com/users");
Request request = new Request.Builder()
.url(javaUrl)
.build();Header Management
Add, set, and remove HTTP headers for the request.
/**
* Sets the header named name to value. If this request already has any
* headers with that name, they are all replaced.
* @param name the header name
* @param value the header value
* @return this builder for method chaining
*/
public Builder header(String name, String value);
/**
* Adds a header with name and value. Prefer this method for multiply-valued
* headers like "Cookie".
* @param name the header name
* @param value the header value
* @return this builder for method chaining
*/
public Builder addHeader(String name, String value);
/**
* Removes all headers with the specified name.
* @param name the header name to remove
* @return this builder for method chaining
*/
public Builder removeHeader(String name);
/**
* Removes all headers on this builder and adds headers.
* @param headers the headers to set
* @return this builder for method chaining
*/
public Builder headers(Headers headers);Usage Examples:
Request request = new Request.Builder()
.url("https://api.example.com/users")
.header("Authorization", "Bearer token123")
.header("Content-Type", "application/json")
.addHeader("Accept", "application/json")
.addHeader("Accept", "text/plain") // Multiple values
.build();
// Using Headers object
Headers headers = new Headers.Builder()
.add("User-Agent", "MyApp/1.0")
.add("Accept-Language", "en-US")
.build();
Request request = new Request.Builder()
.url("https://api.example.com/users")
.headers(headers)
.build();Cache Control
Configure caching directives for the request.
/**
* Sets this request's Cache-Control header, replacing any cache control
* headers already present.
* @param cacheControl the cache control directives
* @return this builder for method chaining
*/
public Builder cacheControl(CacheControl cacheControl);Usage Examples:
// Force network request (bypass cache)
Request request = new Request.Builder()
.url("https://api.example.com/users")
.cacheControl(CacheControl.FORCE_NETWORK)
.build();
// Use cache only
Request request = new Request.Builder()
.url("https://api.example.com/users")
.cacheControl(CacheControl.FORCE_CACHE)
.build();
// Custom cache control
CacheControl cacheControl = new CacheControl.Builder()
.maxAge(60, TimeUnit.SECONDS)
.noCache()
.build();
Request request = new Request.Builder()
.url("https://api.example.com/users")
.cacheControl(cacheControl)
.build();HTTP Methods
Set the HTTP method and optional request body.
/**
* Sets the request method to GET and removes any request body.
* @return this builder for method chaining
*/
public Builder get();
/**
* Sets the request method to HEAD and removes any request body.
* @return this builder for method chaining
*/
public Builder head();
/**
* Sets the request method to POST with the specified body.
* @param body the request body
* @return this builder for method chaining
*/
public Builder post(RequestBody body);
/**
* Sets the request method to DELETE with the specified body.
* @param body the request body
* @return this builder for method chaining
*/
public Builder delete(RequestBody body);
/**
* Sets the request method to DELETE with an empty body.
* @return this builder for method chaining
*/
public Builder delete();
/**
* Sets the request method to PUT with the specified body.
* @param body the request body
* @return this builder for method chaining
*/
public Builder put(RequestBody body);
/**
* Sets the request method to PATCH with the specified body.
* @param body the request body
* @return this builder for method chaining
*/
public Builder patch(RequestBody body);
/**
* Sets the request method and body.
* @param method the HTTP method
* @param body the request body (may be null for methods that don't require a body)
* @return this builder for method chaining
*/
public Builder method(String method, RequestBody body);Usage Examples:
// GET request
Request getRequest = new Request.Builder()
.url("https://api.example.com/users")
.get()
.build();
// POST request with JSON
RequestBody jsonBody = RequestBody.create(
MediaType.parse("application/json"),
"{\"name\":\"John\",\"email\":\"john@example.com\"}"
);
Request postRequest = new Request.Builder()
.url("https://api.example.com/users")
.post(jsonBody)
.build();
// PUT request
RequestBody putBody = RequestBody.create(
MediaType.parse("application/json"),
"{\"id\":1,\"name\":\"John Updated\"}"
);
Request putRequest = new Request.Builder()
.url("https://api.example.com/users/1")
.put(putBody)
.build();
// DELETE request
Request deleteRequest = new Request.Builder()
.url("https://api.example.com/users/1")
.delete()
.build();
// Custom method
Request customRequest = new Request.Builder()
.url("https://api.example.com/users")
.method("OPTIONS", null)
.build();Request Tagging
Attach tags to requests for identification and cancellation.
/**
* Attaches tag to the request. It can be used later to cancel the request.
* If the tag is unspecified or null, the request is canceled by using the
* request itself as the tag.
* @param tag the tag to attach
* @return this builder for method chaining
*/
public Builder tag(Object tag);Usage Examples:
// Tag request for later cancellation
String requestTag = "user-profile-request";
Request request = new Request.Builder()
.url("https://api.example.com/users/1")
.tag(requestTag)
.build();
// Cancel requests with this tag later
client.cancel(requestTag);
// Tag with custom object
class RequestContext {
String userId;
String operation;
}
RequestContext context = new RequestContext();
context.userId = "123";
context.operation = "fetch-profile";
Request request = new Request.Builder()
.url("https://api.example.com/users/123")
.tag(context)
.build();Building the Request
Create the final immutable Request object.
/**
* Creates the Request with the configured parameters.
* @return the built Request
* @throws IllegalStateException if url is null
*/
public Request build();Request Properties
Access properties of the built Request object.
/**
* Returns the HttpUrl representation of the request URL.
* @return the HttpUrl
*/
public HttpUrl httpUrl();
/**
* Returns the java.net.URL representation of the request URL.
* @return the URL
*/
public URL url();
/**
* Returns the java.net.URI representation of the request URL.
* @return the URI
* @throws IOException if URI construction fails
*/
public URI uri() throws IOException;
/**
* Returns the URL as a string.
* @return the URL string
*/
public String urlString();
/**
* Returns the HTTP method (GET, POST, etc.).
* @return the HTTP method
*/
public String method();
/**
* Returns the request headers.
* @return the Headers object
*/
public Headers headers();
/**
* Returns the value of the specified header, or null if not present.
* @param name the header name
* @return the header value or null
*/
public String header(String name);
/**
* Returns all values for the specified header name.
* @param name the header name
* @return list of header values
*/
public List<String> headers(String name);
/**
* Returns the request body, or null if this request doesn't have a body.
* @return the request body or null
*/
public RequestBody body();
/**
* Returns the tag attached to this request, or the request itself if no tag was set.
* @return the tag object
*/
public Object tag();
/**
* Returns true if this request uses HTTPS.
* @return true if HTTPS, false if HTTP
*/
public boolean isHttps();
/**
* Returns the cache control directives for this request.
* @return the CacheControl object
*/
public CacheControl cacheControl();Creating Builder from Existing Request
Modify existing requests by creating new builders.
/**
* Returns a new Builder based on this request.
* @return a new Builder with this request's configuration
*/
public Builder newBuilder();Usage Examples:
// Create base request
Request baseRequest = new Request.Builder()
.url("https://api.example.com/users")
.header("User-Agent", "MyApp/1.0")
.build();
// Create modified request
Request modifiedRequest = baseRequest.newBuilder()
.addHeader("Authorization", "Bearer token123")
.build();
// Change method while keeping other properties
Request postRequest = baseRequest.newBuilder()
.post(RequestBody.create(MediaType.parse("application/json"), "{}"))
.build();Install with Tessl CLI
npx tessl i tessl/maven-com-squareup-okhttp--okhttp