/*
 * Copyright (c) 2008-2017, Hazelcast, Inc. All Rights Reserved.
 *
 * Licensed 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 com.hazelcast.map;

import com.hazelcast.core.IMap;
import com.hazelcast.map.listener.MapListener;
import com.hazelcast.query.Predicate;
import com.hazelcast.spi.annotation.Beta;

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

/**
 * A concurrent, queryable data structure which is used to cache results of a continuous query executed
 * on an {@code IMap}. It can be also thought of as an always up to date view or snapshot of the {@code IMap}.
 * <p/>
 * Typically, {@code QueryCache} is used for performance reasons.
 * <p/>
 * This {@code QueryCache} can be configured via {@link com.hazelcast.config.QueryCacheConfig QueryCacheConfig}.
 * <p/>
 * It can be reached like this:
 * <pre>
 * <code>
 *
 *     IMap map = hzInstance.getMap("mapName");
 *     Predicate predicate = TruePredicate.INSTANCE;
 *     QueryCache cache = map.getQueryCache(cacheName, predicate, includeValue);
 *
 * </code>
 * </pre>
 * <p/>
 * This cache is evictable. The eviction can be configured with {@link com.hazelcast.config.QueryCacheConfig#evictionConfig
 * evictionConfig}. Events caused by {@code IMap} eviction are not reflected to this cache. But the events published after
 * an explicit call to {@link com.hazelcast.core.IMap#evict} are reflected to this cache.
 * <p/>
 * <b>GOTCHAS</b>
 * <ul>
 * <li>
 * This {@code QueryCache} implementation relies on the eventing system, if a listener is attached to this {@code QueryCache}
 * it may receive same event more than once in case of a system failure. Check out {@link QueryCache#tryRecover()}
 * </li>
 * <li>
 * All writes to this {@link QueryCache} is reflected to underlying {@code IMap} and that
 * write operation will eventually be reflected to this {@code QueryCache} after receiving the
 * event of that operation.
 * </li>
 * <li>
 * There are some gotchas same with underlying {@link com.hazelcast.core.IMap IMap} implementation,
 * one should take care of them before using this {@code QueryCache}.
 * Please check gotchas section in {@link com.hazelcast.core.IMap IMap} class for them.
 * </li>
 * </ul>
 * <p/>
 *
 * @param <K> the type of key for this {@code QueryCache}
 * @param <V> the type of value for this {@code QueryCache}
 * @see com.hazelcast.config.QueryCacheConfig
 * @since 3.5
 */
@Beta
public interface QueryCache<K, V> {

    /**
     * @see com.hazelcast.core.IMap#get(Object)
     */
    V get(Object key);

    /**
     * @see com.hazelcast.core.IMap#containsKey(Object)
     */
    boolean containsKey(Object key);

    /**
     * @see com.hazelcast.core.IMap#containsValue(Object)
     */
    boolean containsValue(Object value);

    /**
     * @see IMap#isEmpty()
     */
    boolean isEmpty();

    /**
     * @see IMap#size()
     */
    int size();

    /**
     * @see IMap#addIndex(String, boolean)
     */
    void addIndex(String attribute, boolean ordered);

    /**
     * @see IMap#getAll(Set)
     */
    Map<K, V> getAll(Set<K> keys);

    /**
     * @see IMap#keySet()
     */
    Set<K> keySet();

    /**
     * @see IMap#keySet(Predicate)
     */
    Set<K> keySet(Predicate predicate);

    /**
     * @see IMap#entrySet()
     */
    Set<Map.Entry<K, V>> entrySet();

    /**
     * @see IMap#entrySet(Predicate)
     */
    Set<Map.Entry<K, V>> entrySet(Predicate predicate);

    /**
     * @see IMap#values()
     */
    Collection<V> values();

    /**
     * @see IMap#values(Predicate)
     */
    Collection<V> values(Predicate predicate);

    /**
     * @see IMap#addEntryListener(MapListener, boolean)
     */
    String addEntryListener(MapListener listener, boolean includeValue);

    /**
     * @see IMap#addEntryListener(MapListener, Object, boolean)
     */
    String addEntryListener(MapListener listener, K key, boolean includeValue);

    /**
     * @see IMap#addEntryListener(MapListener, Predicate, boolean)
     */
    String addEntryListener(MapListener listener, Predicate<K, V> predicate, boolean includeValue);

    /**
     * @see IMap#addEntryListener(MapListener, Predicate, Object, boolean)
     */
    String addEntryListener(MapListener listener, Predicate<K, V> predicate, K key, boolean includeValue);

    /**
     * @see IMap#removeEntryListener(String)
     */
    boolean removeEntryListener(String id);

    /**
     * Returns the name of this {@code QueryCache}. The returned value will never be null.
     *
     * @return the name of this {@code QueryCache}.
     */
    String getName();

    /**
     * This method can be used to recover from a possible event loss situation.
     * <p/>
     * This method tries to make consistent the data in this {@code QueryCache} with the data in the underlying {@code IMap}
     * by replaying the events after last consistently received ones. As a result of this replaying logic, same event may
     * appear more than once to the {@code QueryCache} listeners.
     * <p/>
     * This method returns {@code false} if the event is not in the buffer of event publisher side. That means recovery is not
     * possible.
     *
     * @return {@code true} if the {@code QueryCache} content will be eventually consistent, otherwise {@code false}.
     * @see com.hazelcast.config.QueryCacheConfig#bufferSize
     */
    boolean tryRecover();

    /**
     * Destroys this cache.
     * Clears and releases all local and remote resources created for this cache.
     */
    void destroy();

}