0
# Client Operations
1

2
Core client functionality for connecting to CDAP explore services, executing operations, and managing client lifecycle. Provides both direct client interfaces and simplified facade patterns for common operations.
3

4
## Capabilities
5

6
### ExploreClient Interface
7

8
Main client interface for all explore operations, extending Closeable for proper resource management.
9

10
```java { .api }
11
/**
12
 * Client interface for explore operations with lifecycle management
13
 */
14
interface ExploreClient extends Closeable {
15
    /**
16
     * Test connectivity to the explore service
17
     * @throws UnauthenticatedException if the client is not authenticated
18
     * @throws ServiceUnavailableException if the explore service is not available
19
     * @throws ExploreException if there is some other error when attempting to ping the explore service
20
     */
21
    void ping() throws UnauthenticatedException, ServiceUnavailableException, ExploreException;
22
    
23
    /**
24
     * Submit SQL statement for asynchronous execution
25
     * @param namespace namespace context for the query
26
     * @param statement SQL statement to execute
27
     * @return future containing execution results
28
     */
29
    ListenableFuture<ExploreExecutionResult> submit(NamespaceId namespace, String statement);
30
    
31
    /**
32
     * Enable exploration for a dataset
33
     * @param datasetInstance dataset to enable exploration for
34
     * @return future completing when operation finishes
35
     */
36
    ListenableFuture<Void> enableExploreDataset(DatasetId datasetInstance);
37
    
38
    /**
39
     * Enable exploration with detailed specification
40
     * @param datasetInstance dataset to enable
41
     * @param spec dataset specification
42
     * @param truncating whether to truncate existing data
43
     * @return future completing when operation finishes
44
     */
45
    ListenableFuture<Void> enableExploreDataset(DatasetId datasetInstance, 
46
                                               DatasetSpecification spec, boolean truncating);
47
    
48
    /**
49
     * Disable exploration for a dataset
50
     * @param datasetInstance dataset to disable exploration for
51
     * @return future completing when operation finishes
52
     */
53
    ListenableFuture<Void> disableExploreDataset(DatasetId datasetInstance);
54
    
55
    /**
56
     * Enable exploration for a stream with format specification
57
     * @param stream stream to enable exploration for
58
     * @param tableName table name for the stream
59
     * @param format format specification for the stream
60
     * @return future completing when operation finishes
61
     */
62
    ListenableFuture<Void> enableExploreStream(StreamId stream, String tableName, 
63
                                              FormatSpecification format);
64
    
65
    /**
66
     * Disable exploration for a stream
67
     * @param stream stream to disable exploration for
68
     * @param tableName table name for the stream
69
     * @return future completing when operation finishes
70
     */
71
    ListenableFuture<Void> disableExploreStream(StreamId stream, String tableName);
72
}
73
```
74

75
### Client Implementations
76

77
Different client implementations for various deployment scenarios.
78

79
```java { .api }
80
/**
81
 * Explore client using service discovery to find endpoints
82
 */
83
class DiscoveryExploreClient extends AbstractExploreClient {
84
    // Uses Twill discovery service to find explore service endpoints
85
}
86

87
/**
88
 * Explore client with a fixed server address
89
 */
90
class FixedAddressExploreClient extends AbstractExploreClient {
91
    // Connects to a specific explore service endpoint
92
}
93

94
/**
95
 * Explore client with supplier-provided address
96
 */
97
class SuppliedAddressExploreClient extends AbstractExploreClient {
98
    // Uses a supplier to dynamically provide service address
99
}
100

101
/**
102
 * Explore client for program container environments
103
 */
104
class ProgramDiscoveryExploreClient extends DiscoveryExploreClient {
105
    // Specialized for use within CDAP program containers
106
}
107

108
/**
109
 * Mock client implementation for testing
110
 */
111
class MockExploreClient extends AbstractIdleService implements ExploreClient {
112
    // Mock implementation for unit testing scenarios
113
}
114
```
115

116
### ExploreFacade
117

118
Simplified facade providing high-level operations with automatic configuration and error handling.
119

120
```java { .api }
121
/**
122
 * High-level facade for common explore operations
123
 */
124
class ExploreFacade {
125
    /**
126
     * Enable exploration for a dataset with automatic configuration checking
127
     * @param datasetInstance dataset to enable exploration for
128
     * @throws ExploreException if operation fails
129
     */
130
    void enableExploreDataset(DatasetId datasetInstance) throws ExploreException;
131
    
132
    /**
133
     * Enable exploration with specification and truncation option
134
     * @param datasetInstance dataset to enable
135
     * @param spec dataset specification
136
     * @param truncating whether to truncate existing data
137
     * @throws ExploreException if operation fails
138
     */
139
    void enableExploreDataset(DatasetId datasetInstance, DatasetSpecification spec, 
140
                             boolean truncating) throws ExploreException;
141
    
142
    /**
143
     * Update dataset exploration configuration
144
     * @param datasetInstance dataset to update
145
     * @param oldSpec previous specification
146
     * @param newSpec new specification
147
     * @throws ExploreException if operation fails
148
     */
149
    void updateExploreDataset(DatasetId datasetInstance, DatasetSpecification oldSpec, 
150
                             DatasetSpecification newSpec) throws ExploreException;
151
    
152
    /**
153
     * Disable exploration for a dataset
154
     * @param datasetInstance dataset to disable exploration for
155
     * @throws ExploreException if operation fails
156
     */
157
    void disableExploreDataset(DatasetId datasetInstance) throws ExploreException;
158
    
159
    /**
160
     * Create a new namespace for exploration
161
     * @param namespace namespace metadata
162
     * @throws ExploreException if operation fails
163
     */
164
    void createNamespace(NamespaceMeta namespace) throws ExploreException;
165
    
166
    /**
167
     * Remove a namespace from exploration
168
     * @param namespace namespace to remove
169
     * @throws ExploreException if operation fails
170
     */
171
    void removeNamespace(NamespaceId namespace) throws ExploreException;
172
}
173
```
174

175
**Usage Examples:**
176

177
```java
178
import co.cask.cdap.explore.client.ExploreClient;
179
import co.cask.cdap.explore.client.ExploreFacade;
180
import co.cask.cdap.proto.id.DatasetId;
181
import co.cask.cdap.proto.id.NamespaceId;
182

183
// Basic client usage
184
ExploreClient client = // obtained via dependency injection
185
try {
186
    // Test service connectivity
187
    client.ping();
188
    
189
    // Enable dataset exploration
190
    DatasetId dataset = new DatasetId("default", "my_dataset");
191
    ListenableFuture<Void> enableFuture = client.enableExploreDataset(dataset);
192
    enableFuture.get(); // Wait for completion
193
    
194
    // Submit query
195
    ListenableFuture<ExploreExecutionResult> queryFuture = 
196
        client.submit(new NamespaceId("default"), "SELECT COUNT(*) FROM dataset_my_dataset");
197
    
198
    ExploreExecutionResult result = queryFuture.get();
199
    // Process results...
200
    
201
} finally {
202
    client.close();
203
}
204

205
// Using facade for simplified operations
206
ExploreFacade facade = // obtained via dependency injection
207
try {
208
    DatasetId dataset = new DatasetId("default", "simple_dataset");
209
    
210
    // Enable exploration (blocks until complete)
211
    facade.enableExploreDataset(dataset);
212
    
213
    // Disable when done
214
    facade.disableExploreDataset(dataset);
215
    
216
} catch (ExploreException e) {
217
    System.err.println("Explore operation failed: " + e.getMessage());
218
}
219
```
220

221
### Client Configuration
222

223
Configuration and initialization patterns for different deployment scenarios.
224

225
```java { .api }
226
/**
227
 * Guice module for explore client configuration
228
 */
229
class ExploreClientModule extends PrivateModule {
230
    // Configures dependency injection bindings for ExploreClient
231
}
232
```
233

234
**Configuration Properties:**
235
- `explore.enabled` - Enable/disable explore functionality
236
- `explore.http.timeout` - HTTP operation timeout in milliseconds
237
- Service discovery settings for endpoint resolution