/*
 * 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.hadoop.utils;

import org.apache.commons.lang3.tuple.ImmutablePair;
import org.apache.hadoop.classification.InterfaceStability;
import org.apache.hadoop.utils.MetadataKeyFilters.MetadataKeyFilter;

import java.io.Closeable;
import java.io.IOException;
import java.util.List;
import java.util.Map;

/**
 * Interface for key-value store that stores ozone metadata.
 * Ozone metadata is stored as key value pairs, both key and value
 * are arbitrary byte arrays.
 */
@InterfaceStability.Evolving
public interface MetadataStore extends Closeable{

  /**
   * Puts a key-value pair into the store.
   *
   * @param key metadata key
   * @param value metadata value
   */
  void put(byte[] key, byte[] value) throws IOException;

  /**
   * @return true if the metadata store is empty.
   *
   * @throws IOException
   */
  boolean isEmpty() throws IOException;

  /**
   * Returns the value mapped to the given key in byte array.
   *
   * @param key metadata key
   * @return value in byte array
   * @throws IOException
   */
  byte[] get(byte[] key) throws IOException;

  /**
   * Deletes a key from the metadata store.
   *
   * @param key metadata key
   * @throws IOException
   */
  void delete(byte[] key) throws IOException;

  /**
   * Returns a certain range of key value pairs as a list based on a
   * startKey or count. Further a {@link MetadataKeyFilter} can be added to
   * filter keys if necessary. To prevent race conditions while listing
   * entries, this implementation takes a snapshot and lists the entries from
   * the snapshot. This may, on the other hand, cause the range result slight
   * different with actual data if data is updating concurrently.
   * <p>
   * If the startKey is specified and found in levelDB, this key and the keys
   * after this key will be included in the result. If the startKey is null
   * all entries will be included as long as other conditions are satisfied.
   * If the given startKey doesn't exist and empty list will be returned.
   * <p>
   * The count argument is to limit number of total entries to return,
   * the value for count must be an integer greater than 0.
   * <p>
   * This method allows to specify one or more {@link MetadataKeyFilter}
   * to filter keys by certain condition. Once given, only the entries
   * whose key passes all the filters will be included in the result.
   *
   * @param startKey a start key.
   * @param count max number of entries to return.
   * @param filters customized one or more {@link MetadataKeyFilter}.
   * @return a list of entries found in the database or an empty list if the
   * startKey is invalid.
   * @throws IOException if there are I/O errors.
   * @throws IllegalArgumentException if count is less than 0.
   */
  List<Map.Entry<byte[], byte[]>> getRangeKVs(byte[] startKey,
      int count, MetadataKeyFilter... filters)
      throws IOException, IllegalArgumentException;

  /**
   * This method is very similar to {@link #getRangeKVs}, the only
   * different is this method is supposed to return a sequential range
   * of elements based on the filters. While iterating the elements,
   * if it met any entry that cannot pass the filter, the iterator will stop
   * from this point without looking for next match. If no filter is given,
   * this method behaves just like {@link #getRangeKVs}.
   *
   * @param startKey a start key.
   * @param count max number of entries to return.
   * @param filters customized one or more {@link MetadataKeyFilter}.
   * @return a list of entries found in the database.
   * @throws IOException
   * @throws IllegalArgumentException
   */
  List<Map.Entry<byte[], byte[]>> getSequentialRangeKVs(byte[] startKey,
      int count, MetadataKeyFilter... filters)
      throws IOException, IllegalArgumentException;

  /**
   * A batch of PUT, DELETE operations handled as a single atomic write.
   *
   * @throws IOException write fails
   */
  void writeBatch(BatchOperation operation) throws IOException;

  /**
   * Compact the entire database.
   * @throws IOException
   */
  void compactDB() throws IOException;

  /**
   * Destroy the content of the specified database,
   * a destroyed database will not be able to load again.
   * Be very careful with this method.
   *
   * @throws IOException if I/O error happens
   */
  void destroy() throws IOException;

  /**
   * Seek the database to a certain key, returns the key-value
   * pairs around this key based on the given offset. Note, this method
   * can only support offset -1 (left), 0 (current) and 1 (right),
   * any other offset given will cause a {@link IllegalArgumentException}.
   *
   * @param offset offset to the key
   * @param from from which key
   * @return a key-value pair
   * @throws IOException
   */
  ImmutablePair<byte[], byte[]> peekAround(int offset, byte[] from)
      throws IOException, IllegalArgumentException;

  /**
   * Iterates entries in the database from a certain key.
   * Applies the given {@link EntryConsumer} to the key and value of
   * each entry, the function produces a boolean result which is used
   * as the criteria to exit from iteration.
   *
   * @param from the start key
   * @param consumer
   *   a {@link EntryConsumer} applied to each key and value. If the consumer
   *   returns true, continues the iteration to next entry; otherwise exits
   *   the iteration.
   * @throws IOException
   */
  void iterate(byte[] from, EntryConsumer consumer)
      throws IOException;
}