Metadata Operations

/**
 * Table discovery and information retrieval
 */
interface Explore {
    /**
     * Get table descriptions matching pattern
     * @param catalog catalog name (can be null)
     * @param schemaPattern schema name pattern (can be null)
     * @param tableNamePattern table name pattern (can be null) 
     * @param tableTypes list of table types to include (can be null)
     * @return query handle for table metadata results
     * @throws ExploreException if operation fails
     */
    QueryHandle getTables(String catalog, String schemaPattern, 
                         String tableNamePattern, List<String> tableTypes) throws ExploreException, SQLException;
    
    /**
     * Get table names in a specific namespace
     * @param namespace namespace to search
     * @return list of table name information
     * @throws ExploreException if operation fails
     * @throws SQLException if SQL error occurs
     */
    List<TableNameInfo> getTables(String namespace) throws ExploreException, SQLException;
    
    /**
     * Get detailed information about a specific table
     * @param namespace namespace containing the table
     * @param table table name
     * @return table information
     * @throws ExploreException if operation fails
     * @throws SQLException if SQL error occurs
     * @throws TableNotFoundException if table does not exist
     */
    TableInfo getTableInfo(String namespace, String table) 
        throws ExploreException, SQLException, TableNotFoundException;
    
    /**
     * Get table information with database specification
     * @param namespace namespace containing the table
     * @param database database name
     * @param table table name
     * @return table information
     * @throws ExploreException if operation fails
     * @throws TableNotFoundException if table does not exist
     */
    TableInfo getTableInfo(String namespace, String database, String table) 
        throws ExploreException, SQLException, TableNotFoundException;
    
    /**
     * Get available table types
     * @return query handle for table type results
     * @throws ExploreException if operation fails
     * @throws SQLException if SQL error occurs
     */
    QueryHandle getTableTypes() throws ExploreException, SQLException;
}

/**
 * Asynchronous table operations via ExploreClient
 */
interface ExploreClient {
    /**
     * Get table descriptions asynchronously
     * @param catalog catalog name
     * @param schemaPattern schema pattern
     * @param tableNamePattern table name pattern
     * @param tableTypes table types to include
     * @return future containing table metadata results
     */
    ListenableFuture<ExploreExecutionResult> tables(String catalog, String schemaPattern, 
                                                   String tableNamePattern, List<String> tableTypes);
    
    /**
     * Get table types asynchronously
     * @return future containing table type results
     */
    ListenableFuture<ExploreExecutionResult> tableTypes();
}

/**
 * Column metadata operations
 */
interface Explore {
    /**
     * Get column descriptions matching patterns
     * @param catalog catalog name (can be null)
     * @param schemaPattern schema name pattern (can be null)
     * @param tableNamePattern table name pattern (can be null)
     * @param columnNamePattern column name pattern (can be null)
     * @return query handle for column metadata results
     * @throws ExploreException if operation fails
     */
    QueryHandle getColumns(String catalog, String schemaPattern, 
                          String tableNamePattern, String columnNamePattern) throws ExploreException, SQLException;
}

/**
 * Asynchronous column operations
 */
interface ExploreClient {
    /**
     * Get column descriptions asynchronously
     * @param catalog catalog name
     * @param schemaPattern schema pattern
     * @param tableNamePattern table name pattern  
     * @param columnNamePattern column name pattern
     * @return future containing column metadata results
     */
    ListenableFuture<ExploreExecutionResult> columns(String catalog, String schemaPattern,
                                                    String tableNamePattern, String columnNamePattern);
}

/**
 * Column description information
 */
class ColumnDesc {
    /**
     * Get column name
     * @return column name
     */
    public String getName();
    
    /**
     * Get column data type
     * @return column type (e.g., "string", "int", "double")
     */
    public String getType();
    
    /**
     * Get column position in table
     * @return 1-based column position
     */
    public int getPosition();
    
    /**
     * Get column comment/description
     * @return column comment or null if none
     */
    public String getComment();
    
    /**
     * Check if column allows null values
     * @return true if nullable
     */
    public boolean isNullable();
}

/**
 * Schema and catalog operations
 */
interface Explore {
    /**
     * Get catalog names
     * @return query handle for catalog results
     * @throws ExploreException if operation fails
     */
    QueryHandle getCatalogs() throws ExploreException, SQLException;
    
    /**
     * Get schema names matching pattern
     * @param catalog catalog name (can be null)
     * @param schemaPattern schema name pattern (can be null)
     * @return query handle for schema results
     * @throws ExploreException if operation fails
     * @throws SQLException if SQL error occurs
     */
    QueryHandle getSchemas(String catalog, String schemaPattern) throws ExploreException, SQLException;
}

/**
 * Asynchronous schema and catalog operations
 */
interface ExploreClient {
    /**
     * Get catalogs asynchronously
     * @return future containing catalog results
     */
    ListenableFuture<ExploreExecutionResult> catalogs();
    
    /**
     * Get schemas asynchronously
     * @param catalog catalog name
     * @param schemaPattern schema pattern
     * @return future containing schema results
     */
    ListenableFuture<ExploreExecutionResult> schemas(String catalog, String schemaPattern);
}

/**
 * Function metadata operations
 */
interface Explore {
    /**
     * Get function descriptions matching patterns
     * @param catalog catalog name (can be null)
     * @param schemaPattern schema name pattern (can be null)
     * @param functionNamePattern function name pattern (can be null)
     * @return query handle for function metadata results
     * @throws ExploreException if operation fails
     */
    QueryHandle getFunctions(String catalog, String schemaPattern, 
                           String functionNamePattern) throws ExploreException, SQLException;
}

/**
 * Asynchronous function operations
 */
interface ExploreClient {
    /**
     * Get functions asynchronously
     * @param catalog catalog name
     * @param schemaPattern schema pattern
     * @param functionNamePattern function name pattern
     * @return future containing function metadata results
     */
    ListenableFuture<ExploreExecutionResult> functions(String catalog, String schemaPattern,
                                                      String functionNamePattern);
}

/**
 * Database information operations
 */
interface Explore {
    /**
     * Get database information by type
     * @param infoType type of information to retrieve
     * @return metadata information
     * @throws ExploreException if operation fails
     */
    MetaDataInfo getInfo(MetaDataInfo.InfoType infoType) throws ExploreException, SQLException;
    
    /**
     * Get data type information
     * @return query handle for data type results
     * @throws ExploreException if operation fails
     * @throws SQLException if SQL error occurs
     */
    QueryHandle getTypeInfo() throws ExploreException, SQLException;
}

/**
 * Asynchronous database information operations
 */
interface ExploreClient {
    /**
     * Get database information asynchronously
     * @param infoType information type to retrieve
     * @return future containing metadata information
     */
    ListenableFuture<MetaDataInfo> info(MetaDataInfo.InfoType infoType);
    
    /**
     * Get data types asynchronously
     * @return future containing data type results
     */
    ListenableFuture<ExploreExecutionResult> dataTypes();
}

/**
 * Database metadata information
 */
class MetaDataInfo {
    /**
     * Information type enumeration
     */
    public enum InfoType {
        TABLE_TERM, SCHEMA_TERM, CATALOG_TERM, PROCEDURE_TERM,
        MAX_CATALOG_NAME_LENGTH, MAX_SCHEMA_NAME_LENGTH, MAX_TABLE_NAME_LENGTH,
        MAX_COLUMN_NAME_LENGTH, MAX_PROCEDURE_NAME_LENGTH, MAX_USER_NAME_LENGTH,
        // ... additional info types
    }
    
    /**
     * Get string value for the information
     * @return string value or null if not applicable
     */
    public String getStringValue();
    
    /**
     * Get integer value for the information
     * @return integer value or -1 if not applicable
     */
    public int getIntValue();
    
    /**
     * Get long value for the information
     * @return long value or -1 if not applicable
     */
    public long getLongValue();
    
    /**
     * Get short value for the information
     * @return short value or -1 if not applicable
     */
    public short getShortValue();
}

/**
 * Utility for generating explore table names
 */
class ExploreTableNaming {
    /**
     * Get table name for a stream
     * @param streamId stream identifier
     * @return explore table name
     */
    public static String getTableName(StreamId streamId);
    
    /**
     * Get table name for a dataset
     * @param datasetId dataset identifier
     * @return explore table name
     */
    public static String getTableName(DatasetId datasetId);
    
    /**
     * Get table name for dataset with properties
     * @param datasetId dataset identifier
     * @param properties dataset properties
     * @return explore table name
     */
    public static String getTableName(DatasetId datasetId, Map<String, String> properties);
    
    /**
     * Clean table name for Hive compatibility
     * @param name original name
     * @return cleaned name suitable for Hive
     */
    public static String cleanTableName(String name);
}

/**
 * Table name information
 */
class TableNameInfo {
    /**
     * Get table name
     * @return table name
     */
    public String getTableName();
    
    /**
     * Get database name
     * @return database name
     */
    public String getDatabaseName();
    
    /**
     * Get schema name
     * @return schema name or null if not applicable
     */
    public String getSchemaName();
}

/**
 * Detailed table information
 */
class TableInfo {
    /**
     * Get table name
     * @return table name
     */
    public String getName();
    
    /**
     * Get database name
     * @return database name
     */
    public String getDbName();
    
    /**
     * Get table owner
     * @return owner name
     */
    public String getOwner();
    
    /**
     * Get creation time
     * @return creation timestamp
     */
    public long getCreationTime();
    
    /**
     * Get last access time
     * @return last access timestamp
     */
    public long getLastAccessTime();
    
    /**
     * Get table location
     * @return table location path
     */
    public String getLocation();
    
    /**
     * Get table schema (columns)
     * @return list of column descriptors
     */
    public List<ColumnDesc> getSchema();
}

import co.cask.cdap.explore.service.Explore;
import co.cask.cdap.explore.client.ExploreClient;
import co.cask.cdap.proto.ColumnDesc;
import co.cask.cdap.proto.QueryResult;

// Synchronous metadata exploration
Explore explore = // obtained via dependency injection

try {
    // Discover all tables
    QueryHandle tablesHandle = explore.getTables(null, null, null, null);
    List<QueryResult> tableResults = explore.nextResults(tablesHandle, 100);
    
    for (QueryResult result : tableResults) {
        List<Object> columns = result.getColumns();
        String tableName = (String) columns.get(2); // TABLE_NAME column
        System.out.println("Found table: " + tableName);
    }
    explore.close(tablesHandle);
    
    // Get column information for a specific table
    QueryHandle columnsHandle = explore.getColumns(null, null, "my_table", null);
    List<QueryResult> columnResults = explore.nextResults(columnsHandle, 50);
    
    for (QueryResult result : columnResults) {
        List<Object> cols = result.getColumns();
        String colName = (String) cols.get(3); // COLUMN_NAME
        String colType = (String) cols.get(5); // TYPE_NAME
        System.out.println("Column: " + colName + " (" + colType + ")");
    }
    explore.close(columnsHandle);
    
    // Get table information using convenience method
    List<TableNameInfo> tableNames = explore.getTables("default");
    for (TableNameInfo info : tableNames) {
        System.out.println("Table: " + info.getTableName() + 
                          " in database: " + info.getDatabaseName());
    }
    
} catch (ExploreException e) {
    System.err.println("Metadata operation failed: " + e.getMessage());
}

// Asynchronous metadata operations
ExploreClient client = // obtained via dependency injection

try {
    // Get database information
    ListenableFuture<MetaDataInfo> future = 
        client.info(MetaDataInfo.InfoType.MAX_TABLE_NAME_LENGTH);
    MetaDataInfo info = future.get();
    System.out.println("Max table name length: " + info.getIntValue());
    
    // Get all catalogs
    ListenableFuture<ExploreExecutionResult> catalogsFuture = client.catalogs();
    ExploreExecutionResult catalogsResult = catalogsFuture.get();
    
    while (catalogsResult.hasNext()) {
        QueryResult result = catalogsResult.next();
        String catalogName = (String) result.getColumns().get(0);
        System.out.println("Catalog: " + catalogName);
    }
    catalogsResult.close();
    
} catch (Exception e) {
    System.err.println("Async metadata operation failed: " + e.getMessage());
}

// Table naming utilities
import co.cask.cdap.explore.utils.ExploreTableNaming;
import co.cask.cdap.proto.id.DatasetId;
import co.cask.cdap.proto.id.StreamId;

// Generate table names for CDAP entities
DatasetId dataset = new DatasetId("default", "user_events");
String tableName = ExploreTableNaming.getTableName(dataset);
System.out.println("Dataset table name: " + tableName);

StreamId stream = new StreamId("default", "log_stream");
String streamTableName = ExploreTableNaming.getTableName(stream);
System.out.println("Stream table name: " + streamTableName);

// Clean names for Hive compatibility
String cleanName = ExploreTableNaming.cleanTableName("my-special.table_name");
System.out.println("Clean table name: " + cleanName);