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

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

import org.apache.fluo.api.client.scanner.ScannerBuilder;
import org.apache.fluo.api.data.Bytes;
import org.apache.fluo.api.data.Column;
import org.apache.fluo.api.data.RowColumn;
import org.apache.fluo.api.data.Span;

/**
 * Allows users to read from a Fluo table at a certain point in time
 *
 * @since 1.0.0
 */
public interface SnapshotBase {

  /**
   * Retrieves the value (in {@link Bytes}) stored at a given row and {@link Column}. Returns null
   * if does not exist.
   */
  Bytes get(Bytes row, Column column);

  /**
   * Given a row and set of {@link Column}s, retrieves a map contains the values at those
   * {@link Column}s. Only columns that exist will be returned in map.
   */
  Map<Column, Bytes> get(Bytes row, Set<Column> columns);

  /**
   * Given a collection of rows and set of {@link Column}s, retrieves a map contains the values at
   * those rows and {@link Column}s. Only rows and columns that exists will be returned in map.
   */
  Map<Bytes, Map<Column, Bytes>> get(Collection<Bytes> rows, Set<Column> columns);

  /**
   * Given a collection of {@link RowColumn}s, retrieves a map contains the values at those rows and
   * {@link Column}s. Only rows and columns that exists will be returned in map.
   */
  Map<Bytes, Map<Column, Bytes>> get(Collection<RowColumn> rowColumns);

  /**
   * This method is the starting point for constructing a scanner. Scanners can be constructed over
   * a {@link Span} and/or with a subset of columns. Below is simple example of building a scanner.
   * 
   * <pre>
   * <code>
   *   Transaction tx = ...;
   *   Span span = Span.exact("row4");
   *   Column col1 = new Column("fam1","qual1");
   *   Column col2 = new Column("fam1","qual2");
   * 
   *   //create a scanner over row4 fetching columns fam1:qual1 and fam1:qual2
   *   CellScanner cs = tx.scanner().over(span).fetch(col1,col2).build();
   *   for(RowColumnValue rcv : cs) {
   *     //do stuff with rcv
   *   }
   * </code>
   * </pre>
   *
   * <p>
   * The following example shows how to build a row scanner.
   *
   * <pre>
   * {
   *   &#064;code
   *   RowScanner rs = tx.scanner().over(span).fetch(col1, col2).byRow().build();
   *   for (ColumnScanner colScanner : rs) {
   *     Bytes row = colScanner.getRow();
   *     for (ColumnValue cv : colScanner) {
   *       // do stuff with the columns and values in the row
   *     }
   *   }
   * }
   * </pre>
   *
   * @return A scanner builder.
   */

  ScannerBuilder scanner();

  /**
   * Wrapper for {@link #get(Collection)} that uses Strings. All strings are encoded and decoded
   * using UTF-8.
   */
  Map<String, Map<Column, String>> gets(Collection<RowColumn> rowColumns);

  /**
   * Wrapper for {@link #get(Collection, Set)} that uses Strings. All strings are encoded and
   * decoded using UTF-8.
   */
  Map<String, Map<Column, String>> gets(Collection<String> rows, Set<Column> columns);

  /**
   * Wrapper for {@link #get(Bytes, Column)} that uses Strings. All strings are encoded and decoded
   * using UTF-8.
   */
  String gets(String row, Column column);

  /**
   * Wrapper for {@link #get(Bytes, Set)} that uses Strings. All strings are encoded and decoded
   * using UTF-8.
   */
  Map<Column, String> gets(String row, Set<Column> columns);

  /**
   * @return transactions start timestamp allocated from Oracle.
   */
  long getStartTimestamp();
}

@@ -2971,27 +2971,14 @@
   * 
-%7B%0A   *   &#064;
+%3C
 code
+%3E
 %0A   
@@ -3275,17 +3275,23 @@
  %7D%0A   * 
-%7D
+%3C/code%3E
 %0A   * %3C/

fix scanner() javadoc