001/*
002 * (C) Copyright 2014 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 *
016 * Contributors:
017 *     tdelprat
018 *     bdelbosc
019 */
020
021package org.nuxeo.elasticsearch.api;
022
023import java.util.List;
024import java.util.NoSuchElementException;
025
026import org.elasticsearch.client.Client;
027
028import com.google.common.util.concurrent.ListenableFuture;
029
030/**
031 * Administration interface for Elasticsearch service
032 *
033 * @since 5.9.3
034 */
035public interface ElasticSearchAdmin {
036
037    /**
038     * Retrieves the {@link Client} that can be used to access Elasticsearch API
039     *
040     * @since 5.9.3
041     */
042    ESClient getClient();
043
044    /**
045     * Initialize Elasticsearch indexes. Setup the index settings and mapping for each index that has been registered.
046     *
047     * @param dropIfExists if {true} remove an existing index
048     * @since 5.9.3
049     */
050    void initIndexes(boolean dropIfExists);
051
052    /**
053     * Reinitialize an index. This will drop the existing index, recreate it with its settings and mapping, the index
054     * will be empty.
055     *
056     * @since 7.3
057     */
058    void dropAndInitIndex(String indexName);
059
060    /**
061     * Reinitialize the index of a repository. This will drop the existing index, recreate it with its settings and
062     * mapping, the index will be empty.
063     *
064     * @since 7.1
065     */
066    default void dropAndInitRepositoryIndex(String repositoryName) {
067        dropAndInitRepositoryIndex(repositoryName, true);
068    }
069
070    /**
071     * Reinitialize the index of a repository. This will drop the existing index, recreate it with its settings and
072     * mapping, the index will be empty.
073     * When syncAlias is false then search alias is not updated with the new index,
074     * you need to explicitly call {@link #syncSearchAndWriteAlias(String)}
075     *
076     * @since 9.3
077     */
078    void dropAndInitRepositoryIndex(String repositoryName, boolean syncAlias);
079
080    /**
081     * List repository names that have Elasticsearch support.
082     *
083     * @since 7.1
084     */
085    List<String> getRepositoryNames();
086
087    /**
088     * Get the search index name associated with the repository name.
089     *
090     * @throws NoSuchElementException if there is no Elasticsearch index associated with the requested repository.
091     * @since 7.2
092     */
093    String getIndexNameForRepository(String repositoryName);
094
095    /**
096     * Gets the repository name associated with the index.
097     *
098     * @since 9.10
099     */
100    String getRepositoryForIndex(String indexName);
101
102    /**
103     * Get the index names with the given type.
104     *
105     * @since 7.10
106     */
107    List<String> getIndexNamesForType(String type);
108
109    /**
110     * Get the first search index name with the given type.
111     *
112     * @throws NoSuchElementException if there is no Elasticsearch index with the given type.
113     * @since 7.10
114     */
115    String getIndexNameForType(String type);
116
117    /**
118     * Returns the index to use for any write operations.
119     *
120     * @since 9.3
121     */
122    String getWriteIndexName(String searchIndexName);
123
124    /**
125     * Make sure that the search alias point to the same index as the write alias.
126     *
127     * @since 9.3
128     */
129    void syncSearchAndWriteAlias(String searchIndexName);
130
131    /**
132     * Returns true if there are indexing activities scheduled or running.
133     *
134     * @since 5.9.5
135     */
136    boolean isIndexingInProgress();
137
138    /**
139     * A {@link java.util.concurrent.Future} that accepts callback on completion when all the indexing worker are done.
140     *
141     * @since 7.2
142     */
143    ListenableFuture<Boolean> prepareWaitForIndexing();
144
145    /**
146     * Refresh all document indexes, immediately after the operation occurs, so that the updated document appears in
147     * search results immediately. There is no fsync thus doesn't guarantee durability.
148     *
149     * @since 5.9.3
150     */
151    void refresh();
152
153    /**
154     * Refresh document index for the specific repository, immediately after the operation occurs, so that the updated
155     * document appears in search results immediately. There is no fsync thus doesn't guarantee durability.
156     *
157     * @since 5.9.4
158     */
159    void refreshRepositoryIndex(String repositoryName);
160
161    /**
162     * Elasticsearch flush on all document indexes, triggers a lucene commit, empties the transaction log. Data is
163     * flushed to disk.
164     *
165     * @since 5.9.3
166     */
167    void flush();
168
169    /**
170     * Elasticsearch flush on document index for a specific repository, triggers a lucene commit, empties the
171     * transaction log. Data is flushed to disk.
172     *
173     * @since 5.9.4
174     */
175    void flushRepositoryIndex(String repositoryName);
176
177    /**
178     * Elasticsearch run {@link ElasticSearchAdmin#optimizeRepositoryIndex} on all document indexes,
179     *
180     * @since 7.2
181     */
182    void optimize();
183
184    /**
185     * Elasticsearch optimize operation allows to reduce the number of segments to one, Note that this can potentially
186     * be a very heavy operation.
187     *
188     * @since 7.2
189     */
190    void optimizeRepositoryIndex(String repositoryName);
191
192    /**
193     * Elasticsearch optimize operation allows to reduce the number of segments to one, Note that this can potentially
194     * be a very heavy operation.
195     *
196     * @since 7.3
197     */
198    void optimizeIndex(String indexName);
199
200    /**
201     * Returns the number of indexing worker scheduled waiting to be executed.
202     *
203     * @since 7.1
204     */
205    long getPendingWorkerCount();
206
207    /**
208     * Returns the number of indexing worker that are currently running.
209     *
210     * @since 7.1
211     */
212    long getRunningWorkerCount();
213
214    /**
215     * Returns the total number of command processed by Elasticsearch for this Nuxeo instance. Useful for test
216     * assertion.
217     *
218     * @since 5.9.4
219     */
220    int getTotalCommandProcessed();
221
222    /**
223     * Returns true if the Elasticsearch is embedded with Nuxeo, sharing the same JVM.
224     *
225     * @since 7.2
226     */
227    boolean isEmbedded();
228
229    /**
230     * When true use an external version for Elasticsearch document, this enable an optimistic concurrency control
231     * ensuring that an older version of a document never overwrites a newer version.
232     *
233     * @since 8.3
234     */
235    boolean useExternalVersion();
236
237}