/*
 * 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.hive.beeline.hs2connection;

import java.util.Properties;

/**
 * HS2ConnectionFileParser provides a interface to be used by Beeline to parse a configuration (file
 * or otherwise) to return a Java Properties object which contain key value pairs to be used to construct
 * connection URL automatically for the Beeline connection
 */
public interface HS2ConnectionFileParser {
  /**
   * prefix string used for the keys
   */
  public static final String BEELINE_CONNECTION_PROPERTY_PREFIX = "beeline.hs2.connection.";
  /**
   * Property key used to provide the URL prefix for the connection URL
   */
  public static final String URL_PREFIX_PROPERTY_KEY = "url_prefix";
  /**
   * Property key used to provide the default database in the connection URL
   */
  public static final String DEFAULT_DB_PROPERTY_KEY = "defaultDB";
  /**
   * Property key used to provide the hosts in the connection URL
   */
  public static final String HOST_PROPERTY_KEY = "hosts";
  /**
   * Property key used to provide the hive configuration key value pairs in the connection URL
   */
  public static final String HIVE_CONF_PROPERTY_KEY = "hiveconf";
  /**
   * Property key used to provide the hive variables in the connection URL
   */
  public static final String HIVE_VAR_PROPERTY_KEY = "hivevar";

  /**
   * Returns a Java properties object which contain the key value pairs which can be used in the
   * Beeline connection URL<p>
   * The properties returned must include url_prefix and hosts<p>
   * Following are some examples of the URLs and returned properties object<p>
   * <ul>
   * <li> jdbc:hive2://hs2-instance1.example.com:10000/default;user=hive;password=mypassword should
   * return [ "url_prefix"="jdbc:hive2://", "hosts"="hs2-instance1.example.com:10000",
   * "defaultDB"=default, "user"="hive", "password"="mypassword" ]
   * <li>jdbc:hive2://zk-instance1:10001,zk-instance2:10002,zk-instance3:10003/default;
   * serviceDiscoveryMode=zooKeeper;zooKeeperNamespace=hiveserver2 should return [
   * "url_prefix"="jdbc:hive2://",
   * "hosts"="zk-instance1:10001,zk-instance2:10002,zk-instance3:10003", "defaultDB"="default",
   * "serviceDiscoveryMode"="zooKeeper", "zooKeeperNamespace"="hiveserver2" ]
   *
   * <li>If hive_conf_list and hive_var_list is present in the url it should return a comma separated
   * key=value pairs for each of them<p>
   * For example :<p>
   * jdbc:hive2://hs2-instance1.example.com:10000/default;user=hive?hive.cli.print.currentdb=true;
   * hive.cli.print.header=true#hivevar:mytbl=customers;hivevar:mycol=id it should return [
   * "url_prefix"="jdbc:hive2://", "hosts"="hs2-instance1.example.com:10000", "defaultDB"="default",
   * "user"="hive", "hiveconf"="hive.cli.print.currentdb=true, hive.cli.print.header=true",
   * "hivevar"="hivevar:mytb1=customers, hivevar:mycol=id" ]
   * </ul>
   *
   * @return Properties object which contain connection URL properties for Beeline connection. Returns an empty properties
   * object if the connection configuration is not found
   * @throws BeelineHS2ConnectionFileParseException if there is invalid key with appropriate message
   */
  Properties getConnectionProperties() throws BeelineConfFileParseException;
  /**
   *
   * @return returns true if the configuration exists else returns false
   */
  boolean configExists();
}