HTTP Request Base Tutorial

The HTTP Client System provides a comprehensive HTTP communication layer within the aj-http module. It offers two complementary programming paradigms for making HTTP requests: a declarative annotation-based API using dynamic proxies, and an imperative class-based API for direct programmatic control. Both approaches abstract Java's HttpURLConnection while providing features like automatic JSON/form encoding, configurable timeouts, custom headers, and structured response handling.

This document provides an overview of the HTTP client architecture and the two API styles. For implementation details, see:

• Base request lifecycle: Base Request Framework
• Concrete HTTP method classes: HTTP Methods
• Dynamic proxy and annotations: Annotation-Driven API
• Connection initialization and headers: Request Configuration
• Response parsing and error handling: Response Processing
• File uploads and downloads: File Operations

Get Class Tutorial

The Get class is an HTTP GET request implementation used to retrieve resources from a server. It extends the base Request class and provides various convenient methods for API interaction and data retrieval in different formats.

Main Features

1. Multiple Construction Methods: Supports basic URL construction and construction with connection initialization
2. Text Response Retrieval: Direct retrieval of plain text responses
3. JSON Response Processing: Automatic parsing of JSON responses to Map or Java objects
4. XML Response Processing: Parsing XML responses to Map
5. Authentication Support: Built-in Bearer Token authentication support
6. Custom Connection Configuration: Support for custom HTTP connection configuration

Basic Usage

1. Creating Instances

// Basic construction method
Get getRequest = new Get("https://api.example.com/data");

// Construction with connection initialization
Get getRequest = new Get("https://api.example.com/data", conn -> {
    conn.setRequestProperty("User-Agent", "MyApp/1.0");
});

2. Retrieving Text Response

// Simple text retrieval
String response = Get.text("https://api.example.com/data");

// Text retrieval with custom connection configuration
String response = Get.text("https://api.example.com/data", conn -> {
    conn.setRequestProperty("Accept", "text/plain");
});

3. Retrieving JSON Response

// Retrieve JSON response as Map
Map<String, Object> jsonResponse = Get.api("https://api.example.com/data");

// JSON retrieval with authentication token
Map<String, Object> jsonResponse = Get.api("https://api.example.com/data", "your-token");

// JSON retrieval with custom connection configuration
Map<String, Object> jsonResponse = Get.api("https://api.example.com/data", conn -> {
    conn.setRequestProperty("Accept", "application/json");
});

4. Mapping JSON Response to Java Object

// Map to specified class type
MyDataClass data = Get.api("https://api.example.com/data", MyDataClass.class);

// Mapping with authentication token
MyDataClass data = Get.api("https://api.example.com/data", MyDataClass.class, "your-token");

// Mapping with custom connection configuration
MyDataClass data = Get.api("https://api.example.com/data", MyDataClass.class, conn -> {
    conn.setRequestProperty("Accept", "application/json");
});

5. Retrieving XML Response

// Retrieve XML response as Map
Map<String, String> xmlResponse = Get.apiXml("https://api.example.com/data.xml", conn -> {
    conn.setRequestProperty("Accept", "application/xml");
});

Parameter Descriptions

• url: The target URL address for the request
• initConnection: Functional interface for configuring HTTP connection
• token: Bearer authentication token
• clz: Target Java class type for JSON response mapping

Notes

1. All static methods automatically execute the request and return the result
2. Methods with initConnection parameter allow custom HTTP headers and other connection properties
3. JSON responses can be automatically mapped to Java objects, object fields need to match JSON keys
4. XML responses are parsed into simple key-value pair Map

Post Class Tutorial

The Post class is an HTTP POST request implementation that extends the BasePost class, used for sending HTTP POST requests with various content types and data formats.

Main Features

1. Multiple Construction Methods: Supports different parameter combinations for constructing POST requests
2. JSON Data Sending: Built-in support for sending JSON format data
3. Custom Connection Configuration: Supports custom HTTP connection initialization configuration
4. Automatic Response Parsing: Automatically parses responses into Map objects

Basic Usage

1. Creating Instances

// Basic construction method
Post postRequest = new Post("https://api.example.com/data", 
                           "{\"name\":\"test\"}", 
                           "application/json");

// Construction with custom connection configuration
Post postRequest = new Post("https://api.example.com/data",
                           "{\"name\":\"test\"}",
                           "application/json",
                           conn -> {
                               conn.setRequestProperty("Authorization", "Bearer token");
                           });

2. Sending JSON API Requests

// Send JSON data and get response
Map<String, Object> data = ObjectHelper.mapOf("name", "test", "value", 123);
Map<String, Object> response = Post.api("https://api.example.com/data", data);

// JSON request with custom connection configuration
Map<String, Object> response = Post.api("https://api.example.com/data", 
                                       data,
                                       conn -> {
                                           conn.setRequestProperty("Custom-Header", "value");
                                       });

Constructor Descriptions

• Post(HttpMethod method, String url): Creates a request with specified HTTP method and URL
• Post(String url, Object data, String contentType): Creates a request with URL, data, and content type
• Post(String url, Object data, String contentType, Consumer<HttpURLConnection> initConnection): Fully configured constructor

Static Methods

• api(String url, Object data): Sends a JSON format POST request and returns parsed Map
• api(String url, Object data, Consumer<HttpURLConnection> initConnection): JSON POST request with custom connection configuration