Package: ElasticsearchClient

ElasticsearchClient

Coverage

1: /*******************************************************************************
2: * Copyright (c) 2017, 2022 Eurotech and/or its affiliates and others
3: *
4: * This program and the accompanying materials are made
5: * available under the terms of the Eclipse Public License 2.0
6: * which is available at https://www.eclipse.org/legal/epl-2.0/
7: *
8: * SPDX-License-Identifier: EPL-2.0
9: *
10: * Contributors:
11: * Eurotech - initial API and implementation
12: *******************************************************************************/
13: package org.eclipse.kapua.service.elasticsearch.client;
14:
15: import com.fasterxml.jackson.databind.JsonNode;
16: import com.fasterxml.jackson.databind.node.ObjectNode;
17: import org.eclipse.kapua.service.elasticsearch.client.configuration.ElasticsearchClientConfiguration;
18: import org.eclipse.kapua.service.elasticsearch.client.exception.ClientException;
19: import org.eclipse.kapua.service.elasticsearch.client.exception.ClientInitializationException;
20: import org.eclipse.kapua.service.elasticsearch.client.exception.ClientUnavailableException;
21: import org.eclipse.kapua.service.elasticsearch.client.model.BulkUpdateRequest;
22: import org.eclipse.kapua.service.elasticsearch.client.model.BulkUpdateResponse;
23: import org.eclipse.kapua.service.elasticsearch.client.model.IndexRequest;
24: import org.eclipse.kapua.service.elasticsearch.client.model.IndexResponse;
25: import org.eclipse.kapua.service.elasticsearch.client.model.InsertRequest;
26: import org.eclipse.kapua.service.elasticsearch.client.model.InsertResponse;
27: import org.eclipse.kapua.service.elasticsearch.client.model.ResultList;
28: import org.eclipse.kapua.service.elasticsearch.client.model.TypeDescriptor;
29: import org.eclipse.kapua.service.elasticsearch.client.model.UpdateRequest;
30: import org.eclipse.kapua.service.elasticsearch.client.model.UpdateResponse;
31:
32: import java.io.Closeable;
33:
34: /**
35: * Elasticsearch client definition.
36: * <p>
37: * It defines the methods (crud and utilities) to be exposed to the caller.
38: * The Elasticsearch client implementation should provide a static init method and a static getInstance method that return the already initialized client instance.
39: *
40: * @since 1.0.0
41: */
42: public interface ElasticsearchClient<C extends Closeable> {
43:
44: /**
45: * Initializes the underlying Elasticsearch connection.
46: *
47: * @since 1.0.0
48: */
49: void init() throws ClientInitializationException;
50:
51: /**
52: * Closes the underlying Elasticsearch connection.
53: *
54: * @throws ClientUnavailableException If the {@link ElasticsearchClient} was not initialized and this is invoked.
55: * @since 1.0.0
56: */
57: void close() throws ClientUnavailableException;
58:
59: /**
60: * Gets the org.elasticsearch.Client.
61: *
62: * @return The org.elasticsearch.Client.
63: * @since 1.3.0
64: */
65: C getClient();
66:
67: /**
68: * Sets the org.elasticsearch.Client to use with {@link ElasticsearchClient}.
69: *
70: * @param client The org.elasticsearch.Client
71: * @return Itself, to chain invocations.
72: * @since 1.3.0
73: */
74: ElasticsearchClient<C> withClient(C client);
75:
76: /**
77: * Gets the {@link ElasticsearchClientConfiguration}.
78: *
79: * @return The {@link ElasticsearchClientConfiguration}.
80: * @since 1.3.0
81: */
82: ElasticsearchClientConfiguration getClientConfiguration();
83:
84: /**
85: * Sets the {@link ElasticsearchClientConfiguration} to use with the {@link ElasticsearchClient}.
86: *
87: * @param clientConfiguration The {@link ElasticsearchClientConfiguration}.
88: * @return Itself, to chain invocations.
89: * @since 1.3.0
90: */
91: ElasticsearchClient<C> withClientConfiguration(ElasticsearchClientConfiguration clientConfiguration);
92:
93: /**
94: * Gets the {@link ModelContext}
95: *
96: * @return The {@link ModelContext}
97: * @since 1.3.0
98: */
99: ModelContext getModelContext();
100:
101: /**
102: * Sets the {@link ModelContext}.
103: *
104: * @param modelContext The {@link ModelContext}.
105: * @return Itself, to chain invocations.
106: * @since 1.3.0
107: */
108: ElasticsearchClient<C> withModelContext(ModelContext modelContext);
109:
110: /**
111: * Gets the {@link QueryConverter}
112: *
113: * @return The {@link QueryConverter}
114: * @since 1.3.0
115: */
116: QueryConverter getModelConverter();
117:
118: /**
119: * Sets the {@link QueryConverter}.
120: *
121: * @param modelConverter The {@link QueryConverter}.
122: * @return Itself, to chain invocations.
123: * @since 1.3.0
124: */
125: ElasticsearchClient<C> withModelConverter(QueryConverter modelConverter);
126:
127: /**
128: * Inserts a document.
129: *
130: * @param insertRequest The {@link InsertRequest} to perform.
131: * @return The {@link InsertResponse} from Elasticsearch.
132: * @throws ClientException if error occurs while inserting document.
133: * @since 1.0.0
134: */
135: InsertResponse insert(InsertRequest insertRequest) throws ClientException;
136:
137: /**
138: * Upserts a document.
139: *
140: * @param updateRequest The {@link UpdateRequest} to perform.
141: * @return the {@link UpdateResponse} from Elasticsearch
142: * @throws ClientException if error occurs while upserting document.
143: * @since 1.0.0
144: */
145: UpdateResponse upsert(UpdateRequest updateRequest) throws ClientException;
146:
147: /**
148: * Bulk upserts.
149: *
150: * @param bulkUpdateRequest The {@link BulkUpdateRequest} to perform.
151: * @return the {@link BulkUpdateResponse} from Elasticsearch
152: * @throws ClientException if error occurs while upserting documents.
153: * @since 1.0.0
154: */
155: BulkUpdateResponse upsert(BulkUpdateRequest bulkUpdateRequest) throws ClientException;
156:
157: /**
158: * Finds by query.
159: * <p>
160: * This method returns the first result found that matches the query.
161: *
162: * @param typeDescriptor The {@link TypeDescriptor} to look for.
163: * @param query The query to perform.
164: * @param clazz The expected {@link Object#getClass()}
165: * @return The first result found that matches the query.
166: * @throws ClientException if error occurs while querying.
167: * @since 1.0.0
168: */
169: <T> T find(TypeDescriptor typeDescriptor, Object query, Class<T> clazz) throws ClientException;
170:
171: /**
172: * Finds by query.
173: *
174: * @param typeDescriptor The {@link TypeDescriptor} to look for.
175: * @param query The query to perform.
176: * @param clazz The expected {@link Object#getClass()}
177: * @return The {@link ResultList} that matches the query.
178: * @throws ClientException if error occurs while querying.
179: * @since 1.0.0
180: */
181: <T> ResultList<T> query(TypeDescriptor typeDescriptor, Object query, Class<T> clazz) throws ClientException;
182:
183: /**
184: * Counts by query.
185: *
186: * @param typeDescriptor The {@link TypeDescriptor} to look for.
187: * @param query The query to perform.
188: * @return The number of matching results.
189: * @throws ClientException if error occurs while counting.
190: * @since 1.0.0
191: */
192: long count(TypeDescriptor typeDescriptor, Object query) throws ClientException;
193:
194: /**
195: * Deletes by id.
196: *
197: * @param typeDescriptor The {@link TypeDescriptor} to delete.
198: * @param id The id to delete
199: * @throws ClientException if error occurs while deleting.
200: * @since 1.0.0
201: */
202: void delete(TypeDescriptor typeDescriptor, String id) throws ClientException;
203:
204: /**
205: * Deletes by query.
206: *
207: * @param typeDescriptor The {@link TypeDescriptor} to delete.
208: * @param query The query to perform.
209: * @throws ClientException if error occurs while deleting.
210: * @since 1.0.0
211: */
212: void deleteByQuery(TypeDescriptor typeDescriptor, Object query) throws ClientException;
213:
214: //
215: // Indexes / mappings section
216: //
217:
218: /**
219: * Checks if the index exists.
220: *
221: * @param indexRequest The {@link IndexRequest} to perform.
222: * @return The {@link IndexResponse} from Elasticsearch
223: * @throws ClientException if error occurs while checking.
224: * @since 1.0.0
225: */
226: IndexResponse isIndexExists(IndexRequest indexRequest) throws ClientException;
227:
228: /**
229: * Creates the index.
230: *
231: * @param indexName The index name to create.
232: * @param indexSettings The index settings.
233: * @throws ClientException if error occurs while inserting.
234: * @since 1.0.0
235: */
236: void createIndex(String indexName, ObjectNode indexSettings) throws ClientException;
237:
238: /**
239: * Checks if the mapping exists.
240: *
241: * @param typeDescriptor The {@link TypeDescriptor} to look for.
242: * @return {@code true} if mapping exists, {@code false} otherwise
243: * @throws ClientException if error occurs while checking.
244: * @since 1.0.0
245: */
246: boolean isMappingExists(TypeDescriptor typeDescriptor) throws ClientException;
247:
248: /**
249: * Puts the mapping.
250: *
251: * @param typeDescriptor The {@link TypeDescriptor} to put.
252: * @param mapping The mapping to put.
253: * @throws ClientException if error occurs while putting.
254: * @since 1.0.0
255: */
256: void putMapping(TypeDescriptor typeDescriptor, JsonNode mapping) throws ClientException;
257:
258: /**
259: * Forces the Elasticsearch to refresh the indexes.
260: *
261: * @throws ClientException if error occurs while refreshing.
262: * @since 1.0.0
263: */
264: void refreshAllIndexes() throws ClientException;
265:
266: /**
267: * Deletes all indexes.
268: *
269: * <b>
270: * WARNING!
271: * This call will erase the whole database!
272: * Be careful using it! :)
273: * </b>
274: *
275: * @throws ClientException if error occurs while deleting.
276: * @since 1.0.0
277: */
278: void deleteAllIndexes() throws ClientException;
279:
280: /**
281: * Deletes the specified indexes.
282: *
283: * <b>
284: * WARNING!
285: * Once dropped the indexes cannot be restored!
286: * Be careful using it! :)
287: * </b>
288: *
289: * @param indexes the names to be deleted.
290: * @throws ClientException if error occurs while deleting.
291: * @since 1.0.0
292: */
293: void deleteIndexes(String... indexes) throws ClientException;
294:
295: /**
296: * Finds indexes by prefix.
297: *
298: * @param indexRequest The {@link IndexRequest} to perform.
299: * @return The {@link IndexResponse} from Elasticsearch.
300: * @throws ClientException if error occurs while finding.
301: * @since 1.0.0
302: */
303: IndexResponse findIndexes(IndexRequest indexRequest) throws ClientException;
304: }