Now, generate an user manual from code
- User
Now, generate an user manual from code
Assistant
📚 ApiClient User Manual
This document provides a comprehensive guide for using the
ApiClientclass, which is responsible for managing HTTP connections and REST API interactions in your application.
🔧 Overview
The
ApiClientis a singleton class designed to manage network communication with a backend API using Retrofit and OkHttp. It supports:- Creating Retrofit service interfaces
- Tracking network activity (e.g., for UI feedback like loading indicators)
- Handling unauthorized responses globally
- Configuring base URLs
- Proper resource cleanup on shutdown
📦 Package & Class
package it.dirimo.apto.dtt.rest.client;Main class:
public class ApiClientInterface:
public interface Client
📌 Usage Guide
1. ✅ Getting the Singleton Instance
Use
ApiClient.getInstance()to obtain the singleton instance:ApiClient apiClient = ApiClient.getInstance();This ensures only one instance of the client is used throughout the application lifecycle.
2. 🛠️ Accessing the Client Interface
Once you have the instance, get access to the
Clientinterface:Client client = apiClient.getClient();This allows you to create Retrofit services, register event handlers, and more.
3. 🔄 Creating Retrofit Service Interfaces
To interact with your backend APIs, define an interface annotated with Retrofit annotations (e.g.,
@GET,@POST) and use:MyApiService service = client.create(MyApiService.class);Where
MyApiServiceis your Retrofit service interface.
4. 📍 Setting Base URL (Optional)
You can change the base URL dynamically before making any API calls:
client.setBaseUrl("https://api.myapp.com/");⚠️ Note: Changing the base URL after creating Retrofit instances may not take effect unless the
ApiClientis reinitialized or the app restarts.
5. 📣 Registering Call Status Handlers
Register a handler to be notified when network calls start, end, or fail:
client.addClientCallHandler((callStatus) -> { switch (callStatus) { case START: System.out.println("Network call started"); break; case END: System.out.println("Network call completed"); break; case FAILED: System.out.println("Network call failed"); break; } return null; });Remove the handler when no longer needed:
client.removeClientCallHandler(handlerReference);
6. 🔐 Handling Unauthorized Responses (HTTP 401)
Register a handler to respond to unauthorized requests (e.g., token expiration):
client.addUnauthorizedHandler((param) -> { System.out.println("Unauthorized access detected. Redirecting to login..."); // Perform logout or token refresh logic here return null; });Remove the handler when no longer needed:
client.removeUnauthorizedHandler(handlerReference);These handlers are triggered by the
JsonInterceptor.
7. 🕒 Tracking Network Activity (UI Integration)
Use the
callInProgressProperty()to bind UI elements like progress indicators:progressBar.visibleProperty().bind(apiClient.callInProgressProperty()); progressBar.progressProperty().bind(Bindings.when(apiClient.callInProgressProperty()) .then(ProgressIndicator.INDETERMINATE_PROGRESS).otherwise(0));This will automatically show/hide the progress bar based on active network calls.
8. 🚫 Shutting Down the Client
When your application closes or the session ends, properly shut down the client to release resources:
ApiClient.getInstance().shutdown();This ensures:
- The OkHttp dispatcher thread pool is shut down
- All open connections are evicted
- Cache is closed gracefully
📋 Constants Used
URLs
Defined in
Urls.java:public static final String PROD_URL = "https://api.prod.example.com/";You can replace this with development/staging URLs if needed.
📦 Dependencies Required
Ensure the following dependencies are included in your project:
<!-- Retrofit --> <dependency> <groupId>com.squareup.retrofit2</groupId> <artifactId>retrofit</artifactId> <version>2.9.0</version> </dependency> <!-- Gson Converter --> <dependency> <groupId>com.squareup.retrofit2</groupId> <artifactId>converter-gson</artifactId> <version>2.9.0</version> </dependency> <!-- Scalars Converter --> <dependency> <groupId>com.squareup.retrofit2</groupId> <artifactId>converter-scalars</artifactId> <version>2.9.0</version> </dependency> <!-- OkHttp --> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>okhttp</artifactId> <version>4.12.0</version> </dependency> <!-- Logging Interceptor --> <dependency> <groupId>com.squareup.okhttp3</groupId> <artifactId>logging-interceptor</artifactId> <version>4.12.0</version> </dependency> <!-- JavaFX Bindings --> <dependency> <groupId>org.openjfx</groupId> <artifactId>javafx-base</artifactId> <version>17.0.2</version> </dependency>
🧪 Sample Usage
// Get the client Client client = ApiClient.getInstance().getClient(); // Set custom base URL client.setBaseUrl("https://api.testserver.com/"); // Register call status handler client.addClientCallHandler(status -> { System.out.println("Call status changed: " + status); return null; }); // Register unauthorized handler client.addUnauthorizedHandler(v -> { System.out.println("Unauthorized! Please log in again."); return null; }); // Create Retrofit service MyApiService service = client.create(MyApiService.class); // Make a request Call<User> call = service.getUser(123); call.enqueue(new Callback<User>() { @Override public void onResponse(Call<User> call, Response<User> response) { if (response.isSuccessful()) { System.out.println("User: " + response.body().getName()); } } @Override public void onFailure(Call<User> call, Throwable t) { System.err.println("Request failed: " + t.getMessage()); } });
❗ Known Limitations
- Base URL changes are not dynamic: Once the Retrofit instance is created, changing the base URL via
setBaseUrl()won't affect existing Retrofit services. - Multiple simultaneous calls may cause premature UI updates: If multiple calls are running and one fails or ends before others complete,
callInProgressmight be set to false incorrectly. UseaddClientCallHandler()for precise control.
🧹 Cleanup Best Practices
Always remember to:
- Remove all registered handlers when they're no longer needed
- Call
ApiClient.getInstance().shutdown()on application exit
📁 File Structure
it.dirimo.apto.dtt.rest.client ├── ApiClient.java // Main client manager ├── Client.java // Public interface for accessing services and handlers ├── JsonInterceptor.java // Handles HTTP 401 responses ├── Urls.java // Holds base URLs └── UtilDateTypeAdapter.java // Custom GSON adapter for Date type
✅ Summary
Feature Description Singleton Ensures one global instance Retrofit Type-safe HTTP client OkHttp Underlying networking engine Event Listeners Track call status and unauthorized responses Base URL Management Switch between environments Resource Cleanup Graceful shutdown of HTTP clients
For further assistance, contact the Dirimo Logistika team or refer to the official documentation for Retrofit and OkHttp.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.