agoncharuk commented on a change in pull request #64: URL: https://github.com/apache/ignite-3/pull/64#discussion_r595321073
########## File path: modules/metastorage-client/src/main/java/org/apache/ignite/metastorage/client/MetaStorageService.java ########## @@ -0,0 +1,334 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package org.apache.ignite.metastorage.client; + +import java.util.Collection; +import java.util.List; +import java.util.UUID; +import java.util.concurrent.CompletableFuture; +import org.apache.ignite.metastorage.common.CompactedException; +import org.apache.ignite.metastorage.common.Condition; +import org.apache.ignite.metastorage.common.Cursor; +import org.apache.ignite.metastorage.common.Entry; +import org.apache.ignite.metastorage.common.Operation; +import org.apache.ignite.metastorage.common.OperationTimeoutException; +import org.apache.ignite.metastorage.common.WatchListener; +import org.jetbrains.annotations.NotNull; +import org.jetbrains.annotations.Nullable; + +/** + * Defines interface for access to a meta storage service. + */ +public interface MetaStorageService { + /** + * Retrieves an entry for the given key. + * + * @param key Key. Couldn't be {@code null}. + * @return An entry for the given key. Couldn't be {@code null}. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<Entry> get(@NotNull byte[] key); + + /** + * Retrieves an entry for the given key and the revision upper bound. + * + * @param key The key. Couldn't be {@code null}. + * @param revUpperBound The upper bound for entry revisions. Must be positive. + * @return An entry for the given key and maximum revision limited by {@code revUpperBound}. + * Couldn't be {@code null}. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @throws CompactedException If the desired revisions are removed from the storage due to a compaction. + * Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<Entry> get(@NotNull byte[] key, long revUpperBound); + + /** + * Retrieves entries for given keys. + * + * @param keys The collection of keys. Couldn't be {@code null} or empty. + * Collection elements couldn't be {@code null}. + * @return A list of entries for given keys. The order of entries in the result list corresponds to + * the traversal order of {@code keys} collection. Couldn't be {@code null}. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<List<Entry>> getAll(Collection<byte[]> keys); + + /** + * Retrieves entries for given keys and the revision upper bound. + * + * @param keys The collection of keys. Couldn't be {@code null} or empty. + * Collection elements couldn't be {@code null}. + * @param revUpperBound The upper bound for entry revisions. Must be positive. + * @return A list of entries for given keys and maximum revision limited by {@code revUpperBound}. + * The order of entries in the result list corresponds to the traversal order of {@code keys} collection. + * Couldn't be {@code null}. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @throws CompactedException If the desired revisions are removed from the storage due to a compaction. + * Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<List<Entry>> getAll(Collection<byte[]> keys, long revUpperBound); + + /** + * Inserts or updates an entry with the given key and the given value. + * + * @param key The key. Couldn't be {@code null}. + * @param value The value.Couldn't be {@code null}. + * @return Completed future. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<Void> put(@NotNull byte[] key, @NotNull byte[] value); + + /** + * Inserts or updates an entry with the given key and the given value and + * retrieves a previous entry for the given key. + * + * @param key The key. Couldn't be {@code null}. + * @param value The value.Couldn't be {@code null}. + * @return A previous entry for the given key. Couldn't be {@code null}. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<Entry> getAndPut(@NotNull byte[] key, @NotNull byte[] value); + + /** + * Inserts or updates entries with given keys and given values. + * Size of {@code keys} and {@code values} must be the same. + * + * @param keys The list of keys. Couldn't be {@code null} or empty. + * @param values The list of values corresponding to the list of keys. Couldn't be {@code null} or empty. + * @return Completed future. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<Void> putAll(@NotNull List<byte[]> keys, @NotNull List<byte[]> values); + + /** + * Inserts or updates entries with given keys and given values and + * retrieves a previous entries for given keys. + * Size of {@code keys} and {@code values} must be the same. + * + * @param keys The list of keys. Couldn't be {@code null} or empty. + * @param values The list of values corresponding to the list of keys. Couldn't be {@code null} or empty. + * @return A list of entries for given keys. Couldn't be {@code null}. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<List<Entry>> getAndPutAll(@NotNull List<byte[]> keys, @NotNull List<byte[]> values); + + /** + * Removes an entry for the given key. + * + * @param key The key. Couldn't be {@code null}. + * @return Completed future. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<Void> remove(@NotNull byte[] key); + + /** + * Removes an entry for the given key. + * + * @param key The key. Couldn't be {@code null}. + * @return A previous entry for the given key. Couldn't be {@code null}. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<Void> getAndRemove(@NotNull byte[] key); + + /** + * Removes entries for given keys. + * + * @param key The key. Couldn't be {@code null}. + * @return Completed future. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<Void> removeAll(@NotNull Collection<byte[]> key); + + /** + * Removes entries for given keys and retrieves previous entries. + * + * @param key The key. Couldn't be {@code null}. + * @return A list of previous entries for given keys.. + * The order of entries in the result list corresponds to the traversal order of {@code keys} collection. + * Couldn't be {@code null}. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + */ + @NotNull + CompletableFuture<List<Entry>> getAndRemoveAll(@NotNull Collection<byte[]> key); + + + /** + * Updates an entry for the given key conditionally. + * + * <p>Conditional update could be treated as <i>if(condition)-then(success)-else(failure)</i> expression.</p> + * + * @param key The key. Couldn't be {@code null}. + * @param condition The condition. + * @param success The update which will be applied in case of condition evaluation yields {@code true}. + * @param failure The update which will be applied in case of condition evaluation yields {@code false}. + * @return Future result {@code true} if {@code success} update was applied, otherwise {@code false}. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + * @see Condition + * @see Operation + */ + // TODO: https://issues.apache.org/jira/browse/IGNITE-14269: will be replaced by conditional multi update. + @NotNull + CompletableFuture<Boolean> invoke(@NotNull byte[] key, @NotNull Condition condition, + @NotNull Operation success, @NotNull Operation failure); + + /** + * Updates an entry for the given key conditionally. + * + * <p>Conditional update could be treated as <i>if(condition)-then(success)-else(failure)</i> expression.</p> + * + * @param key The key. Couldn't be {@code null}. + * @param condition The condition. + * @param success The update which will be applied in case of condition evaluation yields {@code true}. + * @param failure The update which will be applied in case of condition evaluation yields {@code false}. + * @return A previous entry for the given key. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @see Entry + * @see Condition + * @see Operation + */ + //TODO: https://issues.apache.org/jira/browse/IGNITE-14269: will be replaced by conditional multi update. + @NotNull + CompletableFuture<Entry> getAndInvoke(@NotNull byte[] key, @NotNull Condition condition, + @NotNull Operation success, @NotNull Operation failure); + + /** + * Retrieves entries for the given key range in lexicographic order. Entries will be filtered out by upper bound + * of given revision number. + * + * @param keyFrom Start key of range (inclusive). Couldn't be {@code null}. + * @param keyTo End key of range (exclusive). Could be {@code null}. + * @param revUpperBound The upper bound for entry revision. {@code -1} means latest revision. + * @return Cursor built upon entries corresponding to the given range and revision. + * @throws OperationTimeoutException If the operation is timed out. + * @throws CompactedException If the desired revisions are removed from the storage due to a compaction. + * @see Entry + */ + @NotNull + Cursor<Entry> range(@NotNull byte[] keyFrom, @Nullable byte[] keyTo, long revUpperBound); + + /** + * Retrieves entries for the given key range in lexicographic order. Short cut for + * {@link #range(byte[], byte[], long)} where {@code revUpperBound == -1}. + * + * @param keyFrom Start key of range (inclusive). Couldn't be {@code null}. + * @param keyTo End key of range (exclusive). Could be {@code null}. + * @return Cursor built upon entries corresponding to the given range and revision. + * @throws OperationTimeoutException If the operation is timed out. + * @throws CompactedException If the desired revisions are removed from the storage due to a compaction. + * @see Entry + */ + @NotNull + Cursor<Entry> range(@NotNull byte[] keyFrom, @Nullable byte[] keyTo); + + /** + * Subscribes on meta storage updates matching the parameters. + * + * @param keyFrom Start key of range (inclusive). Could be {@code null}. + * @param keyTo End key of range (exclusive). Could be {@code null}. + * @param revision Start revision inclusive. {@code 0} - all revision, + * {@code -1} - latest revision (accordingly to current meta storage state). + * @param lsnr Listener which will be notified for each update. + * @return Subscription identifier. Could be used in {@link #stopWatch} method in order to cancel subscription. + * @throws OperationTimeoutException If the operation is timed out. Will be thrown on getting future result. + * @throws CompactedException If the desired revisions are removed from the storage due to a compaction. + * Will be thrown on getting future result. + * @see Entry + */ + @NotNull + //TODO: UUID Should be replaced by IgniteUUID when it will be introduced. + CompletableFuture<UUID> watch(@Nullable byte[] keyFrom, @Nullable byte[] keyTo, Review comment: There is a time window between the moment this method returns and the moment the result future obtains a watch ID. Within this window it is impossible to cancel the watch and do the cleanup. Probably, we should generate the watch ID on the client side and return the ID immediately? ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected]
