001/*
002 *
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *     http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019package org.apache.hadoop.hbase.client;
020
021import java.io.IOException;
022import java.util.Map;
023
024import org.apache.yetus.audience.InterfaceAudience;
025import org.apache.hadoop.hbase.util.JsonMapper;
026
027/**
028 * Superclass for any type that maps to a potentially application-level query.
029 * (e.g. Put, Get, Delete, Scan, Next, etc.)
030 * Contains methods for exposure to logging and debugging tools.
031 */
032@InterfaceAudience.Public
033public abstract class Operation {
034  // TODO make this configurable
035  // TODO Do we need this anymore now we have protobuffed it all?
036  private static final int DEFAULT_MAX_COLS = 5;
037
038  /**
039   * Produces a Map containing a fingerprint which identifies the type and 
040   * the static schema components of a query (i.e. column families)
041   * @return a map containing fingerprint information (i.e. column families)
042   */
043  public abstract Map<String, Object> getFingerprint();
044
045  /**
046   * Produces a Map containing a summary of the details of a query 
047   * beyond the scope of the fingerprint (i.e. columns, rows...)
048   * @param maxCols a limit on the number of columns output prior to truncation
049   * @return a map containing parameters of a query (i.e. rows, columns...)
050   */
051  public abstract Map<String, Object> toMap(int maxCols);
052
053  /**
054   * Produces a Map containing a full summary of a query.
055   * @return a map containing parameters of a query (i.e. rows, columns...)
056   */
057  public Map<String, Object> toMap() {
058    return toMap(DEFAULT_MAX_COLS);
059  }
060
061  /**
062   * Produces a JSON object for fingerprint and details exposure in a
063   * parseable format.
064   * @param maxCols a limit on the number of columns to include in the JSON
065   * @return a JSONObject containing this Operation's information, as a string
066   */
067  public String toJSON(int maxCols) throws IOException {
068    return JsonMapper.writeMapAsString(toMap(maxCols));
069  }
070
071  /**
072   * Produces a JSON object sufficient for description of a query
073   * in a debugging or logging context.
074   * @return the produced JSON object, as a string
075   */
076  public String toJSON() throws IOException {
077    return toJSON(DEFAULT_MAX_COLS);
078  }
079
080  /**
081   * Produces a string representation of this Operation. It defaults to a JSON
082   * representation, but falls back to a string representation of the 
083   * fingerprint and details in the case of a JSON encoding failure.
084   * @param maxCols a limit on the number of columns output in the summary
085   * prior to truncation
086   * @return a JSON-parseable String
087   */
088  public String toString(int maxCols) {
089    /* for now this is merely a wrapper from producing a JSON string, but 
090     * toJSON is kept separate in case this is changed to be a less parsable
091     * pretty printed representation.
092     */
093    try {
094      return toJSON(maxCols);
095    } catch (IOException ioe) {
096      return toMap(maxCols).toString();
097    }
098  }
099
100  /**
101   * Produces a string representation of this Operation. It defaults to a JSON
102   * representation, but falls back to a string representation of the
103   * fingerprint and details in the case of a JSON encoding failure.
104   * @return String
105   */
106  @Override
107  public String toString() {
108    return toString(DEFAULT_MAX_COLS);
109  }
110}