PageRenderTime 8434ms CodeModel.GetById 17ms RepoModel.GetById 1ms app.codeStats 0ms

/src/main/java/com/treasuredata/client/TDClientApi.java

https://gitlab.com/github-cloud-corp/td-client-java
Java | 326 lines | 85 code | 61 blank | 180 comment | 0 complexity | 9e6142fedf352b96ebae396deea7c347 MD5 | raw file
  1. /*
  2. * Licensed to the Apache Software Foundation (ASF) under one
  3. * or more contributor license agreements. See the NOTICE file
  4. * distributed with this work for additional information
  5. * regarding copyright ownership. The ASF licenses this file
  6. * to you under the Apache License, Version 2.0 (the
  7. * "License"); you may not use this file except in compliance
  8. * with the License. You may obtain a copy of the License at
  9. *
  10. * http://www.apache.org/licenses/LICENSE-2.0
  11. *
  12. * Unless required by applicable law or agreed to in writing,
  13. * software distributed under the License is distributed on an
  14. * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  15. * KIND, either express or implied. See the License for the
  16. * specific language governing permissions and limitations
  17. * under the License.
  18. */
  19. package com.treasuredata.client;
  20. import com.google.common.base.Function;
  21. import com.treasuredata.client.model.TDBulkImportSession;
  22. import com.treasuredata.client.model.TDBulkLoadSessionStartRequest;
  23. import com.treasuredata.client.model.TDBulkLoadSessionStartResult;
  24. import com.treasuredata.client.model.TDColumn;
  25. import com.treasuredata.client.model.TDDatabase;
  26. import com.treasuredata.client.model.TDExportJobRequest;
  27. import com.treasuredata.client.model.TDJob;
  28. import com.treasuredata.client.model.TDJobList;
  29. import com.treasuredata.client.model.TDJobRequest;
  30. import com.treasuredata.client.model.TDJobSummary;
  31. import com.treasuredata.client.model.TDPartialDeleteJob;
  32. import com.treasuredata.client.model.TDResultFormat;
  33. import com.treasuredata.client.model.TDSaveQueryRequest;
  34. import com.treasuredata.client.model.TDSavedQuery;
  35. import com.treasuredata.client.model.TDSavedQueryHistory;
  36. import com.treasuredata.client.model.TDSavedQueryStartRequest;
  37. import com.treasuredata.client.model.TDSavedQueryUpdateRequest;
  38. import com.treasuredata.client.model.TDTable;
  39. import com.treasuredata.client.model.TDUser;
  40. import com.treasuredata.client.model.TDUserList;
  41. import java.io.File;
  42. import java.io.InputStream;
  43. import java.util.Date;
  44. import java.util.List;
  45. /**
  46. * Treasure Data Client API
  47. */
  48. public interface TDClientApi<ClientImpl>
  49. extends AutoCloseable
  50. {
  51. /**
  52. * Return a TDClientApi implementation that uses the given api key.
  53. * This instance will share the same internal http client, so closing the returned client will invalidate the current instance.
  54. *
  55. * @param newApiKey
  56. * @return
  57. */
  58. ClientImpl withApiKey(String newApiKey);
  59. /**
  60. * Perform user email and password based authentication and return a new client that will use apikey based authentication.
  61. * Similary to {@link #withApiKey(String)} method, closing the returned client will invalidate the current instance.
  62. *
  63. * @param email
  64. * @param password
  65. * @return
  66. */
  67. ClientImpl authenticate(String email, String password);
  68. /**
  69. * Return information about the current user.
  70. * @return A {@link TDUser} instance.
  71. */
  72. TDUser getUser();
  73. /**
  74. * List the users in the current account.
  75. * @return A {@link TDUserList}.
  76. */
  77. TDUserList listUsers();
  78. String serverStatus();
  79. // Database operations
  80. /**
  81. * Get the list of databases
  82. *
  83. * @return list of databases
  84. * @throws TDClientException if failed to retrieve the database list
  85. */
  86. List<String> listDatabaseNames();
  87. /**
  88. * Get the detailed information of databases
  89. *
  90. * @return list of TDDatabase
  91. * @throws TDClientException if failed to retrieve the database list.
  92. */
  93. List<TDDatabase> listDatabases();
  94. /**
  95. * Create a new database
  96. *
  97. * @param databaseName
  98. * @throws TDClientException if the specified database already exists
  99. */
  100. void createDatabase(String databaseName);
  101. void createDatabaseIfNotExists(String databaseName);
  102. /**
  103. * Delete a specified database. Deleting a database deletes all of its belonging tables.
  104. *
  105. * @param databaseName
  106. * @throws TDClientException if no such a database exists
  107. */
  108. void deleteDatabase(String databaseName);
  109. void deleteDatabaseIfExists(String databaseName);
  110. // Table operations
  111. /**
  112. * Get the list of the tables in the specified database
  113. *
  114. * @param databaseName
  115. * @return
  116. * @throws TDClientException
  117. */
  118. List<TDTable> listTables(String databaseName);
  119. boolean existsDatabase(String databaseName);
  120. boolean existsTable(String databaseName, String table);
  121. /**
  122. * Create a new table
  123. *
  124. * @param databaseName
  125. * @param tableName
  126. * @return
  127. * @throws TDClientException
  128. */
  129. void createTable(String databaseName, String tableName);
  130. void createTableIfNotExists(String databaseName, String tableName);
  131. void renameTable(String databaseName, String tableName, String newTableName);
  132. void renameTable(String databaseName, String tableName, String newTableName, boolean overwrite);
  133. void deleteTable(String databaseName, String tableName);
  134. void deleteTableIfExists(String databaseName, String tableName);
  135. TDPartialDeleteJob partialDelete(String databaseName, String tableName, long from, long to);
  136. void swapTables(String databaseName, String tableName1, String tableName2);
  137. // schema API
  138. void updateTableSchema(String databaseName, String tableName, List<TDColumn> newSchema);
  139. /**
  140. * Submit a new job request
  141. *
  142. * @param jobRequest
  143. * @return job_id
  144. * @throws TDClientException
  145. */
  146. String submit(TDJobRequest jobRequest);
  147. TDJobList listJobs();
  148. TDJobList listJobs(long fromJobId, long toJobId);
  149. void killJob(String jobId);
  150. TDJobSummary jobStatus(String jobId);
  151. TDJobSummary jobStatusByDomainKey(String domainKey);
  152. TDJob jobInfo(String jobId);
  153. /**
  154. * Open an input stream to retrieve the job result.
  155. * The input stream will be closed after this method
  156. * <p/>
  157. * You will receive an empty stream if the query has not finished yet.
  158. *
  159. * @param jobId
  160. * @param format
  161. * @param resultStreamHandler
  162. * @return
  163. */
  164. <Result> Result jobResult(String jobId, TDResultFormat format, Function<InputStream, Result> resultStreamHandler);
  165. // bulk import API
  166. List<TDBulkImportSession> listBulkImportSessions();
  167. List<String> listBulkImportParts(String sessionName);
  168. void createBulkImportSession(String sessionName, String databaseName, String tableName);
  169. TDBulkImportSession getBulkImportSession(String sessionName);
  170. void uploadBulkImportPart(String sessionName, String uniquePartName, File path);
  171. void freezeBulkImportSession(String sessionName);
  172. void unfreezeBulkImportSession(String sessionName);
  173. void performBulkImportSession(String sessionName);
  174. void performBulkImportSession(String sessionName, TDJob.Priority priority);
  175. void commitBulkImportSession(String sessionName);
  176. void deleteBulkImportSession(String sessionName);
  177. <Result> Result getBulkImportErrorRecords(String sessionName, Function<InputStream, Result> resultStreamHandler);
  178. /**
  179. * Saved query APIs
  180. */
  181. /**
  182. * Start a query saved on the cloud.
  183. *
  184. * @param name name of the saved query
  185. * @param scheduledTime the return time of TD_SCHEDULED_TIME
  186. * @return job id
  187. */
  188. String startSavedQuery(String name, Date scheduledTime);
  189. /**
  190. * Start a query saved on the cloud.
  191. *
  192. * @return job id
  193. */
  194. String startSavedQuery(TDSavedQueryStartRequest request);
  195. List<TDSavedQuery> listSavedQueries();
  196. /**
  197. * Get the saved query job history. Note that this will only fetch the the 20 latest jobs (at most) in the history.
  198. * To fetch more jobs, use {@link #getSavedQueryHistory(String, Long, Long)}.
  199. *
  200. * @param name The name of the saved query
  201. * @return The job history
  202. */
  203. TDSavedQueryHistory getSavedQueryHistory(String name);
  204. /**
  205. * Get a specific range of the saved query job history.
  206. *
  207. * @param name The name of the saved query
  208. * @param from The first job index to get (inclusive).
  209. * @param to The last job index to get (exclusive).
  210. * @return
  211. */
  212. TDSavedQueryHistory getSavedQueryHistory(String name, Long from, Long to);
  213. /**
  214. * Save a query for scheduling. Use {@link TDSavedQuery#newBuilder(String, TDJob.Type, String, String, String)}
  215. * to create a TDSaveQueryRequest.
  216. *
  217. * @param request
  218. * @return
  219. */
  220. TDSavedQuery saveQuery(TDSaveQueryRequest request);
  221. /**
  222. * Update the saved query of the given name. To build an update request, use {@link TDSavedQuery#newUpdateRequestBuilder()}.
  223. *
  224. * @param name
  225. * @param request
  226. * @return
  227. */
  228. TDSavedQuery updateSavedQuery(String name, TDSavedQueryUpdateRequest request);
  229. /**
  230. * Delete the saved query of the given name.
  231. *
  232. * @param name
  233. * @return
  234. */
  235. TDSavedQuery deleteSavedQuery(String name);
  236. /**
  237. * Start a table export job.
  238. *
  239. * @param jobRequest
  240. * @return job id
  241. */
  242. String submitExportJob(TDExportJobRequest jobRequest);
  243. /*
  244. * Data Connector Bulk Loading Session APIs
  245. */
  246. /**
  247. * Start a Data Connector Bulk Loading Session Job.
  248. * @param name The name of the Data Connector Bulk Loading Session.
  249. * @return job id
  250. */
  251. TDBulkLoadSessionStartResult startBulkLoadSession(String name);
  252. /**
  253. * Start a Data Connector Bulk Loading Session Job.
  254. * @param name The name of the Data Connector Bulk Loading Session.
  255. * @param scheduledTime The unix epoch to use as the scheduled time of the job.
  256. * @return job id
  257. */
  258. TDBulkLoadSessionStartResult startBulkLoadSession(String name, long scheduledTime);
  259. /**
  260. * Start a Data Connector Bulk Loading Session Job.
  261. * @param request
  262. * @return job id
  263. */
  264. TDBulkLoadSessionStartResult startBulkLoadSession(String name, TDBulkLoadSessionStartRequest request);
  265. }