Cluster Management

/**
 * Request to check cluster health status and metrics
 */
class ClusterHealthRequest extends ActionRequest {
    /**
     * Create cluster health request for specified indices
     * @param indices Index names to check health for (empty for cluster-wide)
     */
    ClusterHealthRequest(String... indices);
    
    /**
     * Set request timeout
     * @param timeout Maximum time to wait for response
     */
    ClusterHealthRequest timeout(String timeout);
    
    /**
     * Wait for specific cluster status before returning
     * @param status Minimum cluster status to wait for (GREEN, YELLOW, RED)
     */
    ClusterHealthRequest waitForStatus(ClusterHealthStatus status);
    
    /**
     * Wait for specific number of nodes
     * @param waitForNodes Number of nodes to wait for (e.g., ">=3", "5")
     */
    ClusterHealthRequest waitForNodes(String waitForNodes);
    
    /**
     * Wait for specific number of active shards
     * @param waitForActiveShards Number of active shards to wait for
     */
    ClusterHealthRequest waitForActiveShards(ActiveShardCount waitForActiveShards);
    
    /**
     * Wait for no relocating shards
     * @param waitForNoRelocatingShards Whether to wait for shard relocations to complete
     */
    ClusterHealthRequest waitForNoRelocatingShards(boolean waitForNoRelocatingShards);
    
    /**
     * Wait for no initializing shards
     * @param waitForNoInitializingShards Whether to wait for shard initialization to complete
     */
    ClusterHealthRequest waitForNoInitializingShards(boolean waitForNoInitializingShards);
    
    /**
     * Set priority level for request
     * @param priority Request priority (IMMEDIATE, URGENT, HIGH, NORMAL, LOW, LANGUID)
     */
    ClusterHealthRequest priority(Priority priority);
    
    /**
     * Get target indices
     */
    String[] indices();
}

/**
 * Response containing cluster health information and metrics
 */
class ClusterHealthResponse extends ActionResponse {
    /**
     * Get overall cluster status
     */
    ClusterHealthStatus getStatus();
    
    /**
     * Get cluster name
     */
    String getClusterName();
    
    /**
     * Get number of nodes in cluster
     */
    int getNumberOfNodes();
    
    /**
     * Get number of data nodes
     */
    int getNumberOfDataNodes();
    
    /**
     * Get number of active primary shards
     */
    int getActivePrimaryShards();
    
    /**
     * Get total number of active shards
     */
    int getActiveShards();
    
    /**
     * Get number of relocating shards
     */
    int getRelocatingShards();
    
    /**
     * Get number of initializing shards
     */
    int getInitializingShards();
    
    /**
     * Get number of unassigned shards
     */
    int getUnassignedShards();
    
    /**
     * Get number of delayed unassigned shards
     */
    int getDelayedUnassignedShards();
    
    /**
     * Get active shards percentage
     */
    double getActiveShardsPercent();
    
    /**
     * Check if request timed out
     */
    boolean isTimedOut();
    
    /**
     * Get per-index health information
     */
    Map<String, ClusterIndexHealth> getIndices();
}

/**
 * Cluster health status enumeration
 */
enum ClusterHealthStatus {
    /**
     * All shards are allocated and replicated
     */
    GREEN,
    
    /**
     * All primary shards allocated, some replicas missing
     */
    YELLOW,
    
    /**
     * Some primary shards are not allocated
     */
    RED
}

/**
 * Request to get comprehensive cluster state information
 */
class ClusterStateRequest extends ActionRequest {
    /**
     * Create cluster state request
     */
    ClusterStateRequest();
    
    /**
     * Set whether to retrieve from local node only
     * @param local Whether to get state from local node only
     */
    ClusterStateRequest local(boolean local);
    
    /**
     * Set cluster manager node timeout
     * @param clusterManagerNodeTimeout Timeout for cluster manager operations
     */
    ClusterStateRequest clusterManagerNodeTimeout(String clusterManagerNodeTimeout);
    
    /**
     * Wait for metadata version
     * @param waitForMetadataVersion Minimum metadata version to wait for
     */
    ClusterStateRequest waitForMetadataVersion(long waitForMetadataVersion);
    
    /**
     * Set specific indices to include in state
     * @param indices Index names to include
     */
    ClusterStateRequest indices(String... indices);
    
    /**
     * Include metadata in response
     * @param includeMetadata Whether to include cluster metadata
     */
    ClusterStateRequest metadata(boolean includeMetadata);
    
    /**
     * Include nodes information in response
     * @param includeNodes Whether to include node information
     */
    ClusterStateRequest nodes(boolean includeNodes);
    
    /**
     * Include routing table in response
     * @param includeRoutingTable Whether to include shard routing information
     */
    ClusterStateRequest routingTable(boolean includeRoutingTable);
    
    /**
     * Include blocks information in response
     * @param includeBlocks Whether to include cluster blocks
     */
    ClusterStateRequest blocks(boolean includeBlocks);
}

/**
 * Response containing comprehensive cluster state information
 */
class ClusterStateResponse extends ActionResponse {
    /**
     * Get cluster name
     */
    ClusterName getClusterName();
    
    /**
     * Get complete cluster state
     */
    ClusterState getState();
    
    /**
     * Check if cluster state was retrieved from local node
     */
    boolean isWaitForTimedOut();
}

/**
 * Request to get cluster statistics and metrics
 */
class ClusterStatsRequest extends ActionRequest {
    /**
     * Create cluster stats request
     */
    ClusterStatsRequest();
    
    /**
     * Set specific node IDs to include in stats
     * @param nodeIds Node identifiers to include
     */
    ClusterStatsRequest nodeIds(String... nodeIds);
    
    /**
     * Set request timeout
     * @param timeout Operation timeout
     */
    ClusterStatsRequest timeout(String timeout);
}

/**
 * Response containing cluster statistics and performance metrics
 */
class ClusterStatsResponse extends ActionResponse {
    /**
     * Get cluster status
     */
    ClusterHealthStatus getStatus();
    
    /**
     * Get node statistics
     */
    ClusterStatsNodes getNodesStats();
    
    /**
     * Get indices statistics
     */
    ClusterStatsIndices getIndicesStats();
    
    /**
     * Get timestamp when stats were collected
     */
    long getTimestamp();
}

/**
 * Request to get information about cluster nodes
 */
class NodesInfoRequest extends ActionRequest {
    /**
     * Create nodes info request for specified nodes
     * @param nodeIds Node IDs to get info for (empty for all nodes)
     */
    NodesInfoRequest(String... nodeIds);
    
    /**
     * Add specific metrics to retrieve
     * @param metrics Metric names (settings, os, process, jvm, thread_pool, transport, http, plugins, ingest)
     */
    NodesInfoRequest addMetrics(String... metrics);
    
    /**
     * Clear all metrics (retrieve basic info only)
     */
    NodesInfoRequest clear();
    
    /**
     * Set request timeout
     * @param timeout Operation timeout
     */
    NodesInfoRequest timeout(String timeout);
    
    /**
     * Get target node IDs
     */
    String[] nodeIds();
    
    /**
     * Get requested metrics
     */
    Set<String> requestedMetrics();
}

/**
 * Response containing detailed node information
 */
class NodesInfoResponse extends ActionResponse {
    /**
     * Get cluster name
     */
    ClusterName getClusterName();
    
    /**
     * Get information for all nodes
     */
    List<NodeInfo> getNodes();
    
    /**
     * Get node info by node ID
     * @param nodeId Node identifier
     */
    NodeInfo getNodeById(String nodeId);
    
    /**
     * Get nodes info as map
     */
    Map<String, NodeInfo> getNodesMap();
    
    /**
     * Get any failures that occurred
     */
    List<FailedNodeException> failures();
}

/**
 * Request to get runtime statistics from cluster nodes
 */
class NodesStatsRequest extends ActionRequest {
    /**
     * Create nodes stats request for specified nodes
     * @param nodeIds Node IDs to get stats for (empty for all nodes)
     */
    NodesStatsRequest(String... nodeIds);
    
    /**
     * Add specific metrics to retrieve
     * @param metrics Metric names (indices, os, process, jvm, thread_pool, fs, transport, http, breaker, script, discovery, ingest)
     */
    NodesStatsRequest addMetrics(String... metrics);
    
    /**
     * Clear all metrics
     */
    NodesStatsRequest clear();
    
    /**
     * Set indices flags for detailed index statistics
     * @param flags Index statistics flags (store, indexing, search, get, merge, refresh, flush, warmer, query_cache, fielddata, completion, segments, translog, request_cache, recovery)
     */
    NodesStatsRequest indices(CommonStatsFlags flags);
    
    /**
     * Set request timeout
     * @param timeout Operation timeout
     */
    NodesStatsRequest timeout(String timeout);
    
    /**
     * Get target node IDs
     */
    String[] nodeIds();
}

/**
 * Response containing runtime node statistics
 */
class NodesStatsResponse extends ActionResponse {
    /**
     * Get cluster name
     */
    ClusterName getClusterName();
    
    /**
     * Get statistics for all nodes
     */
    List<NodeStats> getNodes();
    
    /**
     * Get node stats by node ID
     * @param nodeId Node identifier
     */
    NodeStats getNodeById(String nodeId);
    
    /**
     * Get nodes stats as map
     */
    Map<String, NodeStats> getNodesMap();
    
    /**
     * Get any failures that occurred
     */
    List<FailedNodeException> failures();
}

/**
 * Request to update cluster settings
 */
class ClusterUpdateSettingsRequest extends ActionRequest {
    /**
     * Create cluster update settings request
     */
    ClusterUpdateSettingsRequest();
    
    /**
     * Set persistent settings (survive cluster restarts)
     * @param persistentSettings Settings that persist across restarts
     */
    ClusterUpdateSettingsRequest persistentSettings(Settings persistentSettings);
    
    /**
     * Set persistent settings from map
     * @param source Settings as key-value pairs
     */
    ClusterUpdateSettingsRequest persistentSettings(Map<String, Object> source);
    
    /**
     * Set transient settings (lost on cluster restart)
     * @param transientSettings Settings that are temporary
     */
    ClusterUpdateSettingsRequest transientSettings(Settings transientSettings);
    
    /**
     * Set transient settings from map
     * @param source Settings as key-value pairs
     */
    ClusterUpdateSettingsRequest transientSettings(Map<String, Object> source);
    
    /**
     * Set request timeout
     * @param timeout Operation timeout
     */
    ClusterUpdateSettingsRequest timeout(String timeout);
    
    /**
     * Set cluster manager node timeout
     * @param clusterManagerNodeTimeout Timeout for cluster manager operations
     */
    ClusterUpdateSettingsRequest clusterManagerNodeTimeout(String clusterManagerNodeTimeout);
    
    /**
     * Get persistent settings
     */
    Settings persistentSettings();
    
    /**
     * Get transient settings
     */
    Settings transientSettings();
}

/**
 * Response for cluster settings update operations
 */
class ClusterUpdateSettingsResponse extends ActionResponse {
    /**
     * Check if update was acknowledged
     */
    boolean isAcknowledged();
    
    /**
     * Get updated persistent settings
     */
    Settings getPersistentSettings();
    
    /**
     * Get updated transient settings
     */
    Settings getTransientSettings();
}

/**
 * Request to retrieve current cluster settings
 */
class ClusterGetSettingsRequest extends ActionRequest {
    /**
     * Create cluster get settings request
     */
    ClusterGetSettingsRequest();
    
    /**
     * Include default settings in response
     * @param includeDefaults Whether to include default cluster settings
     */
    ClusterGetSettingsRequest includeDefaults(boolean includeDefaults);
    
    /**
     * Set request timeout
     * @param timeout Operation timeout
     */
    ClusterGetSettingsRequest timeout(String timeout);
    
    /**
     * Set cluster manager node timeout
     * @param clusterManagerNodeTimeout Timeout for cluster manager operations
     */
    ClusterGetSettingsRequest clusterManagerNodeTimeout(String clusterManagerNodeTimeout);
}

/**
 * Response containing current cluster settings
 */
class ClusterGetSettingsResponse extends ActionResponse {
    /**
     * Get persistent settings
     */
    Settings getPersistentSettings();
    
    /**
     * Get transient settings
     */
    Settings getTransientSettings();
    
    /**
     * Get default settings (if requested)
     */
    Settings getDefaultSettings();
}

/**
 * Request to list currently running tasks
 */
class ListTasksRequest extends ActionRequest {
    /**
     * Create list tasks request
     */
    ListTasksRequest();
    
    /**
     * Set specific node IDs to get tasks from
     * @param nodeIds Node identifiers to query
     */
    ListTasksRequest setNodeIds(String... nodeIds);
    
    /**
     * Set task actions to filter by
     * @param actions Action names to include
     */
    ListTasksRequest setActions(String... actions);
    
    /**
     * Set parent task ID to filter by
     * @param parentTaskId Parent task identifier
     */
    ListTasksRequest setParentTaskId(TaskId parentTaskId);
    
    /**
     * Include detailed task information
     * @param detailed Whether to include detailed task info
     */
    ListTasksRequest setDetailed(boolean detailed);
    
    /**
     * Set request timeout
     * @param timeout Operation timeout
     */
    ListTasksRequest setTimeout(String timeout);
}

/**
 * Response containing list of running tasks
 */
class ListTasksResponse extends ActionResponse {
    /**
     * Get all task information
     */
    List<TaskInfo> getTasks();
    
    /**
     * Get tasks grouped by node
     */
    Map<String, List<TaskInfo>> getPerNodeTasks();
    
    /**
     * Get any node failures
     */
    List<TaskOperationFailure> getNodeFailures();
    
    /**
     * Get any task failures
     */
    List<TaskOperationFailure> getTaskFailures();
}

/**
 * Request to cancel running tasks
 */
class CancelTasksRequest extends ActionRequest {
    /**
     * Create cancel tasks request
     */
    CancelTasksRequest();
    
    /**
     * Set specific task ID to cancel
     * @param taskId Task identifier to cancel
     */
    CancelTasksRequest setTaskId(TaskId taskId);
    
    /**
     * Set node IDs to cancel tasks on
     * @param nodeIds Node identifiers
     */
    CancelTasksRequest setNodeIds(String... nodeIds);
    
    /**
     * Set actions to cancel tasks for
     * @param actions Action names to cancel
     */
    CancelTasksRequest setActions(String... actions);
    
    /**
     * Set parent task ID to cancel child tasks
     * @param parentTaskId Parent task identifier
     */
    CancelTasksRequest setParentTaskId(TaskId parentTaskId);
}

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

// Basic cluster health check
ClusterHealthRequest request = new ClusterHealthRequest();
request.timeout(TimeValue.timeValueSeconds(10));
request.waitForStatus(ClusterHealthStatus.YELLOW);

ClusterHealthResponse response = client.admin().cluster().health(request);

System.out.println("Cluster status: " + response.getStatus());
System.out.println("Number of nodes: " + response.getNumberOfNodes());
System.out.println("Number of data nodes: " + response.getNumberOfDataNodes());
System.out.println("Active shards: " + response.getActiveShards());
System.out.println("Unassigned shards: " + response.getUnassignedShards());
System.out.println("Active shards percentage: " + response.getActiveShardsPercent());

// Check specific indices health
ClusterHealthRequest indexHealthRequest = new ClusterHealthRequest("products", "orders");
indexHealthRequest.waitForActiveShards(ActiveShardCount.ALL);
ClusterHealthResponse indexHealthResponse = client.admin().cluster().health(indexHealthRequest);

for (Map.Entry<String, ClusterIndexHealth> entry : indexHealthResponse.getIndices().entrySet()) {
    String indexName = entry.getKey();
    ClusterIndexHealth indexHealth = entry.getValue();
    System.out.println("Index: " + indexName + ", Status: " + indexHealth.getStatus());
}

import org.opensearch.action.admin.cluster.node.info.NodesInfoRequest;
import org.opensearch.action.admin.cluster.node.info.NodesInfoResponse;
import org.opensearch.action.admin.cluster.node.info.NodeInfo;

// Get detailed node information
NodesInfoRequest nodesInfoRequest = new NodesInfoRequest();
nodesInfoRequest.addMetrics("os", "process", "jvm", "transport", "http", "plugins");

NodesInfoResponse nodesInfoResponse = client.admin().cluster().nodesInfo(nodesInfoRequest);

for (NodeInfo nodeInfo : nodesInfoResponse.getNodes()) {
    System.out.println("Node ID: " + nodeInfo.getNode().getId());
    System.out.println("Node name: " + nodeInfo.getNode().getName());
    System.out.println("Host: " + nodeInfo.getNode().getHostName());
    System.out.println("Roles: " + nodeInfo.getNode().getRoles());
    
    if (nodeInfo.getOs() != null) {
        System.out.println("OS: " + nodeInfo.getOs().getName());
        System.out.println("Available processors: " + nodeInfo.getOs().getAvailableProcessors());
    }
    
    if (nodeInfo.getJvm() != null) {
        System.out.println("JVM version: " + nodeInfo.getJvm().getVersion());
        System.out.println("JVM heap max: " + nodeInfo.getJvm().getMem().getHeapMax());
    }
}

import org.opensearch.action.admin.cluster.node.stats.NodesStatsRequest;
import org.opensearch.action.admin.cluster.node.stats.NodesStatsResponse;
import org.opensearch.action.admin.cluster.node.stats.NodeStats;
import org.opensearch.indices.NodeIndicesStats;

// Get runtime node statistics
NodesStatsRequest statsRequest = new NodesStatsRequest();
statsRequest.addMetrics("indices", "os", "process", "jvm", "thread_pool", "fs");

NodesStatsResponse statsResponse = client.admin().cluster().nodesStats(statsRequest);

for (NodeStats nodeStats : statsResponse.getNodes()) {
    System.out.println("Node: " + nodeStats.getNode().getName());
    
    // JVM statistics
    if (nodeStats.getJvm() != null) {
        System.out.println("JVM heap used: " + nodeStats.getJvm().getMem().getHeapUsed());
        System.out.println("JVM heap percentage: " + nodeStats.getJvm().getMem().getHeapUsedPercent());
        System.out.println("JVM uptime: " + nodeStats.getJvm().getUptime());
    }
    
    // OS statistics
    if (nodeStats.getOs() != null) {
        System.out.println("CPU percentage: " + nodeStats.getOs().getCpu().getPercent());
        System.out.println("Load average: " + Arrays.toString(nodeStats.getOs().getCpu().getLoadAverage()));
    }
    
    // Indices statistics
    NodeIndicesStats indicesStats = nodeStats.getIndices();
    if (indicesStats != null) {
        System.out.println("Indexing operations: " + indicesStats.getIndexing().getTotal().getIndexCount());
        System.out.println("Search operations: " + indicesStats.getSearch().getTotal().getQueryCount());
        System.out.println("Documents count: " + indicesStats.getDocs().getCount());
    }
}

import org.opensearch.action.admin.cluster.settings.ClusterUpdateSettingsRequest;
import org.opensearch.action.admin.cluster.settings.ClusterUpdateSettingsResponse;
import org.opensearch.common.settings.Settings;

// Update cluster settings
ClusterUpdateSettingsRequest updateRequest = new ClusterUpdateSettingsRequest();

// Set persistent settings (survive restart)
Settings persistentSettings = Settings.builder()
    .put("cluster.routing.allocation.enable", "all")
    .put("cluster.routing.allocation.cluster_concurrent_rebalance", 2)
    .put("indices.recovery.max_bytes_per_sec", "40mb")
    .build();

updateRequest.persistentSettings(persistentSettings);

// Set transient settings (temporary)
Settings transientSettings = Settings.builder()
    .put("cluster.routing.allocation.disk.watermark.low", "85%")
    .put("cluster.routing.allocation.disk.watermark.high", "90%")
    .put("logger.org.opensearch.index.search.slowlog.query", "DEBUG")
    .build();

updateRequest.transientSettings(transientSettings);

ClusterUpdateSettingsResponse updateResponse = client.admin().cluster().updateSettings(updateRequest);
System.out.println("Settings updated: " + updateResponse.isAcknowledged());

// Retrieve current settings
ClusterGetSettingsRequest getRequest = new ClusterGetSettingsRequest();
getRequest.includeDefaults(true);

ClusterGetSettingsResponse getResponse = client.admin().cluster().getSettings(getRequest);
System.out.println("Persistent settings: " + getResponse.getPersistentSettings());
System.out.println("Transient settings: " + getResponse.getTransientSettings());

import org.opensearch.action.admin.cluster.node.tasks.list.ListTasksRequest;
import org.opensearch.action.admin.cluster.node.tasks.list.ListTasksResponse;
import org.opensearch.action.admin.cluster.node.tasks.cancel.CancelTasksRequest;
import org.opensearch.tasks.TaskInfo;

// List all running tasks
ListTasksRequest listRequest = new ListTasksRequest();
listRequest.setDetailed(true);
listRequest.setActions("indices:data/write/bulk*", "indices:data/read/search*");

ListTasksResponse listResponse = client.admin().cluster().listTasks(listRequest);

System.out.println("Running tasks:");
for (TaskInfo task : listResponse.getTasks()) {
    System.out.println("Task ID: " + task.getTaskId());
    System.out.println("Action: " + task.getAction());
    System.out.println("Description: " + task.getDescription());
    System.out.println("Start time: " + task.getStartTime());
    System.out.println("Running time: " + task.getRunningTimeNanos() / 1_000_000 + "ms");
    
    // Cancel long-running tasks if needed
    if (task.getRunningTimeNanos() > TimeValue.timeValueMinutes(5).nanos()) {
        CancelTasksRequest cancelRequest = new CancelTasksRequest();
        cancelRequest.setTaskId(task.getTaskId());
        
        client.admin().cluster().cancelTasks(cancelRequest);
        System.out.println("Cancelled long-running task: " + task.getTaskId());
    }
}

/**
 * Cluster state container with metadata, routing, and node information
 */
class ClusterState implements Streamable {
    /**
     * Get cluster metadata
     */
    Metadata metadata();
    
    /**
     * Get routing table
     */
    RoutingTable routingTable();
    
    /**
     * Get discovery nodes
     */
    DiscoveryNodes nodes();
    
    /**
     * Get cluster blocks
     */
    ClusterBlocks blocks();
    
    /**
     * Get state version
     */
    long version();
    
    /**
     * Get state UUID
     */
    String stateUUID();
}

/**
 * Node information container with static node details
 */
class NodeInfo implements Streamable {
    /**
     * Get discovery node information
     */
    DiscoveryNode getNode();
    
    /**
     * Get node settings
     */
    Settings getSettings();
    
    /**
     * Get operating system information
     */
    OsInfo getOs();
    
    /**
     * Get process information
     */
    ProcessInfo getProcess();
    
    /**
     * Get JVM information
     */
    JvmInfo getJvm();
    
    /**
     * Get transport information
     */
    TransportInfo getTransport();
    
    /**
     * Get HTTP information
     */
    HttpInfo getHttp();
    
    /**
     * Get installed plugins
     */
    List<PluginInfo> getPlugins();
}

/**
 * Node runtime statistics container
 */
class NodeStats implements Streamable {
    /**
     * Get discovery node information
     */
    DiscoveryNode getNode();
    
    /**
     * Get indices statistics
     */
    NodeIndicesStats getIndices();
    
    /**
     * Get operating system statistics
     */
    OsStats getOs();
    
    /**
     * Get process statistics
     */
    ProcessStats getProcess();
    
    /**
     * Get JVM statistics
     */
    JvmStats getJvm();
    
    /**
     * Get thread pool statistics
     */
    ThreadPoolStats getThreadPool();
    
    /**
     * Get filesystem statistics
     */
    FsInfo getFs();
    
    /**
     * Get transport statistics
     */
    TransportStats getTransport();
}

/**
 * Task identifier for tracking operations
 */
class TaskId implements Streamable {
    /**
     * Get node ID where task is running
     */
    String getNodeId();
    
    /**
     * Get task sequence number
     */
    long getId();
    
    /**
     * Create task ID from string representation
     * @param taskId String in format "nodeId:taskNumber"
     */
    static TaskId fromString(String taskId);
}

/**
 * Request priority levels
 */
enum Priority {
    IMMEDIATE,
    URGENT, 
    HIGH,
    NORMAL,
    LOW,
    LANGUID
}