modules/core/src/main/java/org/apache/ignite/internal/client/GridClientData.java

/*
 * 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.internal.client;

import java.util.Collection;
import java.util.Map;
import java.util.Set;
import java.util.UUID;

/**
 * A data projection of grid client. Contains various methods for cache operations and metrics retrieval.
 * An instance of data projection over some remote cache is provided via
 * {@link GridClient#data(String)} method.
 * <h1 class="header">Affinity Awareness</h1>
 * One of the unique properties of the Ignite remote clients is that they are
 * affinity aware. In other words, both compute and data APIs will optionally
 * contact exactly the node where the data is cached based on some affinity key.
 * This allows for collocation of computations and data and avoids extra network
 * hops that would be necessary if non-affinity nodes were contacted. By default
 * all operations on {@code GridClientData} API will be affinity-aware unless
 * such behavior is overridden by pinning one or more remote nodes
 * (see {@link #pinNodes(GridClientNode, GridClientNode...)} for more information).
 */
public interface GridClientData {
    /**
     * Gets name of the remote cache. The cache name for this projection was specified
     * via {@link GridClient#data(String)} method at the time of creation.
     *
     * @return Name of the remote cache.
     */
    public String cacheName();

    /**
     * Gets client data projection which will only contact specified remote grid node. By default, remote
     * node is determined based on {@link GridClientDataAffinity} provided - this method allows
     * to override default behavior and use only specified server for all cache operations.
     * <p>
     * Use this method when there are other than {@code key-affinity} reasons why a certain
     * node should be contacted.
     *
     * @param node Node to be contacted (optional).
     * @param nodes Additional nodes (optional).
     * @return Client data which will only contact server with given node ID.
     * @throws GridClientException If resulting projection is empty.
     */
    public GridClientData pinNodes(GridClientNode node, GridClientNode... nodes) throws GridClientException;

    /**
     * Gets pinned node or {@code null} if no nodes were pinned.
     *
     * @return Pinned node.
     */
    public Collection<GridClientNode> pinnedNodes();

    /**
     * Puts value to cache on remote grid.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to put in cache.
     * @param val Value to put in cache.
     * @return Whether value was actually put to cache.
     * @throws GridClientException In case of error.
     * @throws GridServerUnreachableException If none of the servers can be reached.
     * @throws GridClientClosedException If client was closed manually.
     */
    public <K, V> boolean put(K key, V val) throws GridClientException;

    /**
     * Asynchronously puts value to cache on remote node.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to put in cache.
     * @param val Value to put in cache.
     * @return Future whether value was actually put to cache.
     */
    public <K, V> GridClientFuture<Boolean> putAsync(K key, V val);

    /**
     * Puts entries to cache on remote grid.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote nodes on which these keys are supposed to be cached (unless
     * some nodes were {@code pinned}). If entries do not map to one node, then the node
     * which has most mapped entries will be contacted.
     *
     * @param entries Entries to put in cache.
     * @throws GridClientException In case of error.
     * @throws GridServerUnreachableException If none of the servers can be reached.
     * @throws GridClientClosedException If client was closed manually.
     */
    public <K, V> void putAll(Map<K, V> entries) throws GridClientException;

    /**
     * Asynchronously puts entries to cache on remote grid.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote nodes on which these keys are supposed to be cached (unless
     * some nodes were {@code pinned}). If entries do not map to one node, then the node
     * which has most mapped entries will be contacted.
     *
     * @param entries Entries to put in cache.
     * @return Future whether this operation completes.
     */
    public <K, V> GridClientFuture<?> putAllAsync(Map<K, V> entries);

    /**
     * Gets value from cache on remote node.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to get from cache.
     * @return Value for given key or {@code null} if no value was cached.
     * @throws GridClientException In case of error.
     * @throws GridServerUnreachableException If none of the servers can be reached.
     * @throws GridClientClosedException If client was closed manually.
     */
    public <K, V> V get(K key) throws GridClientException;

    /**
     * Asynchronously gets value from cache on remote grid.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to get from cache.
     * @return Future with value for given key or with {@code null} if no value was cached.
     */
    public <K, V> GridClientFuture<V> getAsync(K key);

    /**
     * Gets entries from cache on remote grid.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote nodes on which these keys are supposed to be cached (unless
     * some nodes were {@code pinned}). If entries do not map to one node, then the node
     * which has most mapped entries will be contacted.
     *
     * @param keys Keys to get.
     * @throws GridClientException In case of error.
     * @return Entries retrieved from remote cache nodes.
     * @throws GridServerUnreachableException If none of the servers can be reached.
     * @throws GridClientClosedException If client was closed manually.
     */
    public <K, V> Map<K, V> getAll(Collection<K> keys) throws GridClientException;

    /**
     * Asynchronously gets entries from cache on remote grid.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote nodes on which these keys are supposed to be cached (unless
     * some nodes were {@code pinned}). If entries do not map to one node, then the node
     * which has most mapped entries will be contacted.
     *
     * @param keys Keys to get.
     * @return Future with entries retrieved from remote cache nodes.
     */
    public <K, V> GridClientFuture<Map<K, V>> getAllAsync(Collection<K> keys);

    /**
     * Removes value from cache on remote node.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to remove.
     * @return Whether value was actually removed.
     * @throws GridClientException In case of error.
     * @throws GridServerUnreachableException If none of the servers can be reached.
     * @throws GridClientClosedException If client was closed manually.
     */
    public <K> boolean remove(K key) throws GridClientException;

    /**
     * Asynchronously removes value from cache on remote grid.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to remove.
     * @return Future whether value was actually removed.
     */
    public <K> GridClientFuture<Boolean> removeAsync(K key);

    /**
     * Removes entries from cache on remote node.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote nodes on which these keys are supposed to be cached (unless
     * some nodes were {@code pinned}). If entries do not map to one node, then the node
     * which has most mapped entries will be contacted.
     *
     * @param keys Keys to remove.
     * @throws GridClientException In case of error.
     * @throws GridServerUnreachableException If none of the servers can be reached.
     * @throws GridClientClosedException If client was closed manually.
     */
    public <K> void removeAll(Collection<K> keys) throws GridClientException;

    /**
     * Asynchronously removes entries from cache on remote grid.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote nodes on which these keys are supposed to be cached (unless
     * some nodes were {@code pinned}). If entries do not map to one node, then the node
     * which has most mapped entries will be contacted.
     *
     * @param keys Keys to remove.
     * @return Future whether operation finishes.
     */
    public <K> GridClientFuture<?> removeAllAsync(Collection<K> keys);

    /**
     * Replaces value in cache on remote grid only if there was a {@code non-null}
     * value associated with this key.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to replace.
     * @param val Value to replace.
     * @return Whether value was actually replaced.
     * @throws GridClientException In case of error.
     * @throws GridServerUnreachableException If none of the servers can be reached.
     * @throws GridClientClosedException If client was closed manually.
     */
    public <K, V> boolean replace(K key, V val) throws GridClientException;

    /**
     * Asynchronously replaces value in cache on remote grid only if there was a {@code non-null}
     * value associated with this key.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to replace.
     * @param val Value to replace.
     * @return Future whether value was actually replaced.
     */
    public <K, V> GridClientFuture<Boolean> replaceAsync(K key, V val);

    /**
     * Sets entry value to {@code val1} if current value is {@code val2} with
     * following conditions:
     * <ul>
     * <li>
     * If {@code val1} is {@code null} and {@code val2} is equal to current value,
     * entry is removed from cache.
     * </li>
     * <li>
     * If {@code val2} is {@code null}, entry is created if it doesn't exist.
     * </li>
     * <li>
     * If both {@code val1} and {@code val2} are {@code null}, entry is removed.
     * </li>
     * </ul>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to set.
     * @param val1 Value to set.
     * @param val2 Check value.
     * @return Whether value of entry was changed.
     * @throws GridClientException In case of error.
     * @throws GridServerUnreachableException If none of the servers can be reached.
     * @throws GridClientClosedException If client was closed manually.
     */
    public <K, V> boolean cas(K key, V val1, V val2) throws GridClientException;

    /**
     * Asynchronously sets entry value to {@code val1} if current value is {@code val2}
     * with following conditions:
     * <ul>
     * <li>
     * If {@code val1} is {@code null} and {@code val2} is equal to current value,
     * entry is removed from cache.
     * </li>
     * <li>
     * If {@code val2} is {@code null}, entry is created if it doesn't exist.
     * </li>
     * <li>
     * If both {@code val1} and {@code val2} are {@code null}, entry is removed.
     * </li>
     * </ul>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to set.
     * @param val1 Value to set.
     * @param val2 Check value.
     * @return Future whether value of entry was changed.
     */
    public <K, V> GridClientFuture<Boolean> casAsync(K key, V val1, V val2);

    /**
     * Gets affinity node ID for provided key. This method will return {@code null} if no
     * affinity was configured for the given cache for this client or there are no nodes in topology with
     * cache enabled.
     *
     * @param key Key.
     * @return Node ID.
     * @throws GridClientException In case of error.
     */
    public <K> UUID affinity(K key) throws GridClientException;

    /**
     * Fetches metrics for cache from remote grid.
     *
     * @return Cache metrics.
     * @throws GridClientException In case of error.
     * @throws GridServerUnreachableException If none of the servers can be reached.
     * @throws GridClientClosedException If client was closed manually.
     */
    public GridClientDataMetrics metrics() throws GridClientException;

    /**
     * Asynchronously fetches metrics for cache from remote grid.
     *
     * @return Future with cache metrics.
     */
    public GridClientFuture<GridClientDataMetrics> metricsAsync();

    /**
     * Tries to get metrics from local cache.
     * <p>
     * Local cache is updated on every {@link #metrics()} or {@link #metricsAsync()} call
     * if {@link GridClientConfiguration#isEnableMetricsCache()} is enabled. If it is
     * disabled then this method will always return {@code null}.
     *
     * @return Cached metrics or {@code null} if no cached metrics available.
     * @throws GridClientException In case of error.
     * @throws GridServerUnreachableException If none of the servers can be reached.
     * @throws GridClientClosedException If client was closed manually.
     */
    public GridClientDataMetrics cachedMetrics() throws GridClientException;

    /**
     * Append requested value to already cached one. This method supports work with strings, lists and maps.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to manipulate cache value for.
     * @param val Value to append to the cached one.
     * @return Whether value of entry was changed.
     * @throws GridClientException In case of error.
     */
    public <K, V> boolean append(K key, V val) throws GridClientException;

    /**
     * Append requested value to already cached one. This method supports work with strings, lists and maps.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to manipulate cache value for.
     * @param val Value to append to the cached one.
     * @return Future whether value of entry was changed.
     * @throws GridClientException In case of error.
     */
    public <K, V> GridClientFuture<Boolean> appendAsync(K key, V val) throws GridClientException;

    /**
     * Prepend requested value to already cached one. This method supports work with strings, lists and maps.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to manipulate cache value for.
     * @param val Value to prepend to the cached one.
     * @return Whether value of entry was changed.
     * @throws GridClientException In case of error.
     */
    public <K, V> boolean prepend(K key, V val) throws GridClientException;

    /**
     * Prepend requested value to already cached one. This method supports work with strings, lists and maps.
     * <p>
     * Note that this operation is affinity-aware and will immediately contact
     * exactly the remote node on which this key is supposed to be cached (unless
     * some nodes were {@code pinned}).
     *
     * @param key Key to manipulate cache value for.
     * @param val Value to prepend to the cached one.
     * @return Future whether value of entry was changed.
     * @throws GridClientException In case of error.
     */
    public <K, V> GridClientFuture<Boolean> prependAsync(K key, V val) throws GridClientException;

    /**
     * Gets cache flags enabled on this data projection.
     *
     * @return Flags for this data projection (empty set if no flags have been set).
     */
    public Set<GridClientCacheFlag> flags();

    /**
     * Creates new client data object with enabled cache flags.
     *
     * @param flags Optional cache flags to be enabled.
     * @return New client data object.
     * @throws GridClientException In case of error.
     */
    public GridClientData flagsOn(GridClientCacheFlag... flags) throws GridClientException;

    /**
     * Creates new client data object with disabled cache flags.
     *
     * @param flags Cache flags to be disabled.
     * @return New client data object.
     * @throws GridClientException In case of error.
     */
    public GridClientData flagsOff(GridClientCacheFlag... flags) throws GridClientException;
}