Client Operations

/**
 * Client interface for explore operations with lifecycle management
 */
interface ExploreClient extends Closeable {
    /**
     * Test connectivity to the explore service
     * @throws UnauthenticatedException if the client is not authenticated
     * @throws ServiceUnavailableException if the explore service is not available
     * @throws ExploreException if there is some other error when attempting to ping the explore service
     */
    void ping() throws UnauthenticatedException, ServiceUnavailableException, ExploreException;
    
    /**
     * Submit SQL statement for asynchronous execution
     * @param namespace namespace context for the query
     * @param statement SQL statement to execute
     * @return future containing execution results
     */
    ListenableFuture<ExploreExecutionResult> submit(NamespaceId namespace, String statement);
    
    /**
     * Enable exploration for a dataset
     * @param datasetInstance dataset to enable exploration for
     * @return future completing when operation finishes
     */
    ListenableFuture<Void> enableExploreDataset(DatasetId datasetInstance);
    
    /**
     * Enable exploration with detailed specification
     * @param datasetInstance dataset to enable
     * @param spec dataset specification
     * @param truncating whether to truncate existing data
     * @return future completing when operation finishes
     */
    ListenableFuture<Void> enableExploreDataset(DatasetId datasetInstance, 
                                               DatasetSpecification spec, boolean truncating);
    
    /**
     * Disable exploration for a dataset
     * @param datasetInstance dataset to disable exploration for
     * @return future completing when operation finishes
     */
    ListenableFuture<Void> disableExploreDataset(DatasetId datasetInstance);
    
    /**
     * Enable exploration for a stream with format specification
     * @param stream stream to enable exploration for
     * @param tableName table name for the stream
     * @param format format specification for the stream
     * @return future completing when operation finishes
     */
    ListenableFuture<Void> enableExploreStream(StreamId stream, String tableName, 
                                              FormatSpecification format);
    
    /**
     * Disable exploration for a stream
     * @param stream stream to disable exploration for
     * @param tableName table name for the stream
     * @return future completing when operation finishes
     */
    ListenableFuture<Void> disableExploreStream(StreamId stream, String tableName);
}

/**
 * Explore client using service discovery to find endpoints
 */
class DiscoveryExploreClient extends AbstractExploreClient {
    // Uses Twill discovery service to find explore service endpoints
}

/**
 * Explore client with a fixed server address
 */
class FixedAddressExploreClient extends AbstractExploreClient {
    // Connects to a specific explore service endpoint
}

/**
 * Explore client with supplier-provided address
 */
class SuppliedAddressExploreClient extends AbstractExploreClient {
    // Uses a supplier to dynamically provide service address
}

/**
 * Explore client for program container environments
 */
class ProgramDiscoveryExploreClient extends DiscoveryExploreClient {
    // Specialized for use within CDAP program containers
}

/**
 * Mock client implementation for testing
 */
class MockExploreClient extends AbstractIdleService implements ExploreClient {
    // Mock implementation for unit testing scenarios
}

/**
 * High-level facade for common explore operations
 */
class ExploreFacade {
    /**
     * Enable exploration for a dataset with automatic configuration checking
     * @param datasetInstance dataset to enable exploration for
     * @throws ExploreException if operation fails
     */
    void enableExploreDataset(DatasetId datasetInstance) throws ExploreException;
    
    /**
     * Enable exploration with specification and truncation option
     * @param datasetInstance dataset to enable
     * @param spec dataset specification
     * @param truncating whether to truncate existing data
     * @throws ExploreException if operation fails
     */
    void enableExploreDataset(DatasetId datasetInstance, DatasetSpecification spec, 
                             boolean truncating) throws ExploreException;
    
    /**
     * Update dataset exploration configuration
     * @param datasetInstance dataset to update
     * @param oldSpec previous specification
     * @param newSpec new specification
     * @throws ExploreException if operation fails
     */
    void updateExploreDataset(DatasetId datasetInstance, DatasetSpecification oldSpec, 
                             DatasetSpecification newSpec) throws ExploreException;
    
    /**
     * Disable exploration for a dataset
     * @param datasetInstance dataset to disable exploration for
     * @throws ExploreException if operation fails
     */
    void disableExploreDataset(DatasetId datasetInstance) throws ExploreException;
    
    /**
     * Create a new namespace for exploration
     * @param namespace namespace metadata
     * @throws ExploreException if operation fails
     */
    void createNamespace(NamespaceMeta namespace) throws ExploreException;
    
    /**
     * Remove a namespace from exploration
     * @param namespace namespace to remove
     * @throws ExploreException if operation fails
     */
    void removeNamespace(NamespaceId namespace) throws ExploreException;
}

import co.cask.cdap.explore.client.ExploreClient;
import co.cask.cdap.explore.client.ExploreFacade;
import co.cask.cdap.proto.id.DatasetId;
import co.cask.cdap.proto.id.NamespaceId;

// Basic client usage
ExploreClient client = // obtained via dependency injection
try {
    // Test service connectivity
    client.ping();
    
    // Enable dataset exploration
    DatasetId dataset = new DatasetId("default", "my_dataset");
    ListenableFuture<Void> enableFuture = client.enableExploreDataset(dataset);
    enableFuture.get(); // Wait for completion
    
    // Submit query
    ListenableFuture<ExploreExecutionResult> queryFuture = 
        client.submit(new NamespaceId("default"), "SELECT COUNT(*) FROM dataset_my_dataset");
    
    ExploreExecutionResult result = queryFuture.get();
    // Process results...
    
} finally {
    client.close();
}

// Using facade for simplified operations
ExploreFacade facade = // obtained via dependency injection
try {
    DatasetId dataset = new DatasetId("default", "simple_dataset");
    
    // Enable exploration (blocks until complete)
    facade.enableExploreDataset(dataset);
    
    // Disable when done
    facade.disableExploreDataset(dataset);
    
} catch (ExploreException e) {
    System.err.println("Explore operation failed: " + e.getMessage());
}

/**
 * Guice module for explore client configuration
 */
class ExploreClientModule extends PrivateModule {
    // Configures dependency injection bindings for ExploreClient
}