Client APIs

/**
 * Main client interface for all OpenSearch operations.
 * Provides typed access to cluster operations with async support.
 */
interface Client extends Closeable {
    /**
     * Execute an action with typed request and response handling
     * @param action The action type to execute
     * @param request The request parameters
     * @param listener Callback for async response handling
     */
    <Request extends ActionRequest, Response extends ActionResponse>
    void execute(ActionType<Response> action, Request request, ActionListener<Response> listener);
    
    /**
     * Execute an action synchronously
     * @param action The action type to execute  
     * @param request The request parameters
     * @return The response object
     */
    <Request extends ActionRequest, Response extends ActionResponse>
    Response execute(ActionType<Response> action, Request request);
    
    /**
     * Get administrative client for cluster and index management
     */
    AdminClient admin();
    
    /**
     * Get client settings configuration
     */
    Settings settings();
    
    /**
     * Close client and release resources
     */
    void close();
}

import org.opensearch.client.Client;
import org.opensearch.action.search.SearchRequest;
import org.opensearch.action.search.SearchResponse;
import org.opensearch.action.ActionListener;

// Synchronous execution
SearchRequest request = new SearchRequest("products");
SearchResponse response = client.execute(SearchAction.INSTANCE, request);

// Asynchronous execution
client.execute(SearchAction.INSTANCE, request, new ActionListener<SearchResponse>() {
    @Override
    public void onResponse(SearchResponse response) {
        System.out.println("Search completed: " + response.getHits().getTotalHits().value);
    }
    
    @Override
    public void onFailure(Exception e) {
        System.err.println("Search failed: " + e.getMessage());
    }
});

/**
 * Administrative operations client providing access to cluster and index management
 */
interface AdminClient {
    /**
     * Get cluster administration client
     */
    ClusterAdminClient cluster();
    
    /**
     * Get index administration client  
     */
    IndicesAdminClient indices();
}

/**
 * Cluster-level administrative operations
 */
interface ClusterAdminClient {
    /**
     * Execute cluster health check
     */
    void health(ClusterHealthRequest request, ActionListener<ClusterHealthResponse> listener);
    
    /**
     * Get cluster state information
     */
    void state(ClusterStateRequest request, ActionListener<ClusterStateResponse> listener);
    
    /**
     * Get cluster statistics
     */
    void stats(ClusterStatsRequest request, ActionListener<ClusterStatsResponse> listener);
    
    /**
     * Update cluster settings
     */
    void updateSettings(ClusterUpdateSettingsRequest request, 
        ActionListener<ClusterUpdateSettingsResponse> listener);
    
    /**
     * Get node information
     */
    void nodesInfo(NodesInfoRequest request, ActionListener<NodesInfoResponse> listener);
    
    /**
     * Get node statistics
     */
    void nodesStats(NodesStatsRequest request, ActionListener<NodesStatsResponse> listener);
}

/**
 * Index-level administrative operations
 */
interface IndicesAdminClient {
    /**
     * Create an index
     */
    void create(CreateIndexRequest request, ActionListener<CreateIndexResponse> listener);
    
    /**
     * Delete an index
     */
    void delete(DeleteIndexRequest request, ActionListener<AcknowledgedResponse> listener);
    
    /**
     * Get index information
     */
    void get(GetIndexRequest request, ActionListener<GetIndexResponse> listener);
    
    /**
     * Put index mapping
     */
    void putMapping(PutMappingRequest request, ActionListener<AcknowledgedResponse> listener);
    
    /**
     * Get index mappings
     */
    void getMappings(GetMappingsRequest request, ActionListener<GetMappingsResponse> listener);
    
    /**
     * Update index settings
     */
    void updateSettings(UpdateSettingsRequest request, ActionListener<AcknowledgedResponse> listener);
    
    /**
     * Refresh index
     */
    void refresh(RefreshRequest request, ActionListener<RefreshResponse> listener);
}

/**
 * Node-specific client implementation providing direct access to local node
 */
class NodeClient extends AbstractClient {
    /**
     * Create node client with specified node reference
     * @param node The node instance to connect to
     */
    NodeClient(Node node);
    
    /**
     * Get the local node reference
     */
    Node getLocalNode();
    
    /**
     * Get node ID
     */
    String getLocalNodeId();
}

/**
 * Low-level REST client for HTTP operations against OpenSearch cluster
 */
class RestClient implements Closeable {
    /**
     * Create REST client builder with host configuration
     * @param hosts Array of cluster hosts to connect to
     */
    static RestClientBuilder builder(HttpHost... hosts);
    
    /**
     * Perform synchronous HTTP request
     * @param request HTTP request to execute
     * @return HTTP response
     * @throws IOException if request fails
     */
    Response performRequest(Request request) throws IOException;
    
    /**
     * Perform asynchronous HTTP request  
     * @param request HTTP request to execute
     * @param responseListener Callback for response handling
     */
    void performRequestAsync(Request request, ResponseListener responseListener);
    
    /**
     * Close client and release resources
     */
    void close() throws IOException;
}

/**
 * Builder for REST client configuration
 */
class RestClientBuilder {
    /**
     * Set request configuration options
     */
    RestClientBuilder setRequestConfigCallback(RequestConfigCallback requestConfigCallback);
    
    /**
     * Set HTTP client configuration
     */
    RestClientBuilder setHttpClientConfigCallback(HttpClientConfigCallback httpClientConfigCallback);
    
    /**
     * Set default headers for all requests
     */
    RestClientBuilder setDefaultHeaders(Header[] defaultHeaders);
    
    /**
     * Set node selector for request routing
     */
    RestClientBuilder setNodeSelector(NodeSelector nodeSelector);
    
    /**
     * Build the REST client instance
     */
    RestClient build();
}

/**
 * HTTP request representation for REST client operations
 */
class Request {
    /**
     * Create HTTP request
     * @param method HTTP method (GET, POST, PUT, DELETE)
     * @param endpoint API endpoint path
     */
    Request(String method, String endpoint);
    
    /**
     * Add request parameter
     */
    void addParameter(String name, String value);
    
    /**
     * Set request entity body
     */
    void setEntity(HttpEntity entity);
    
    /**
     * Set JSON entity from string
     */
    void setJsonEntity(String json);
    
    /**
     * Get HTTP method
     */
    String getMethod();
    
    /**
     * Get endpoint path
     */
    String getEndpoint();
}

/**
 * HTTP response representation
 */
class Response {
    /**
     * Get response status line
     */
    StatusLine getStatusLine();
    
    /**
     * Get response entity
     */
    HttpEntity getEntity();
    
    /**
     * Get response headers
     */
    Header[] getHeaders();
    
    /**
     * Get response host information
     */
    HttpHost getHost();
}

/**
 * Callback interface for asynchronous response handling
 */
interface ResponseListener {
    /**
     * Called on successful response
     */
    void onSuccess(Response response);
    
    /**
     * Called on request failure
     */
    void onFailure(Exception exception);
}

/**
 * Request configuration options
 */
class RequestOptions {
    /**
     * Default request options
     */
    static final RequestOptions DEFAULT;
    
    /**
     * Create request options builder
     */
    static Builder toBuilder();
    
    /**
     * Get request headers
     */
    List<Header> getHeaders();
    
    /**
     * Get request configuration
     */
    RequestConfig getRequestConfig();
    
    /**
     * Builder for request options
     */
    static class Builder {
        /**
         * Add request header
         */
        Builder addHeader(String name, String value);
        
        /**
         * Set request configuration
         */
        Builder setRequestConfig(RequestConfig requestConfig);
        
        /**
         * Build request options
         */
        RequestOptions build();
    }
}

import org.opensearch.client.RestClient;
import org.opensearch.client.RestClientBuilder;
import org.opensearch.client.Request;
import org.opensearch.client.Response;
import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.impl.client.BasicCredentialsProvider;

// Basic client setup
RestClient client = RestClient.builder(
    new HttpHost("localhost", 9200, "http"),
    new HttpHost("localhost", 9201, "http")
).build();

// With authentication
CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
credentialsProvider.setCredentials(AuthScope.ANY, 
    new UsernamePasswordCredentials("username", "password"));

RestClient secureClient = RestClient.builder(
    new HttpHost("localhost", 9200, "https")
).setHttpClientConfigCallback(httpClientBuilder -> 
    httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider)
).build();

import org.opensearch.action.admin.cluster.health.ClusterHealthRequest;
import org.opensearch.action.admin.cluster.health.ClusterHealthResponse;
import org.opensearch.cluster.health.ClusterHealthStatus;

// Check cluster health
ClusterHealthRequest healthRequest = new ClusterHealthRequest();
healthRequest.timeout("10s");
healthRequest.waitForStatus(ClusterHealthStatus.YELLOW);

client.admin().cluster().health(healthRequest, new ActionListener<ClusterHealthResponse>() {
    @Override
    public void onResponse(ClusterHealthResponse response) {
        System.out.println("Cluster status: " + response.getStatus());
        System.out.println("Number of nodes: " + response.getNumberOfNodes());
    }
    
    @Override
    public void onFailure(Exception e) {
        System.err.println("Health check failed: " + e.getMessage());
    }
});

import org.opensearch.OpenSearchException;
import org.opensearch.OpenSearchTimeoutException;
import org.opensearch.rest.RestStatus;

try {
    SearchResponse response = client.execute(SearchAction.INSTANCE, searchRequest);
    // Process response
} catch (OpenSearchTimeoutException e) {
    System.err.println("Request timed out: " + e.getMessage());
} catch (OpenSearchException e) {
    System.err.println("OpenSearch error: " + e.status() + " - " + e.getMessage());
    if (e.status() == RestStatus.NOT_FOUND) {
        // Handle missing index/document
    }
} catch (Exception e) {
    System.err.println("General error: " + e.getMessage());
}

/**
 * Callback interface for asynchronous action execution
 */
interface ActionListener<Response> {
    /**
     * Called when action completes successfully
     * @param response The action response
     */
    void onResponse(Response response);
    
    /**
     * Called when action fails  
     * @param e The failure exception
     */
    void onFailure(Exception e);
}

/**
 * Base class for all action requests
 */
abstract class ActionRequest implements Streamable, Validatable {
    /**
     * Validate request parameters
     * @return Validation result
     */
    ActionRequestValidationException validate();
}

/**
 * Base class for all action responses  
 */
abstract class ActionResponse implements Streamable {
    // Response base functionality
}

/**
 * Configuration callback for HTTP client setup
 */
interface HttpClientConfigCallback {
    /**
     * Customize HTTP client builder
     */
    HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder);
}

/**
 * Configuration callback for request setup
 */
interface RequestConfigCallback {
    /**
     * Customize request configuration
     */
    RequestConfig.Builder customizeRequestConfig(RequestConfig.Builder requestConfigBuilder);
}