/*
 * $Id$
 *
 * This file is part of the Cloud Services Integration Platform (CSIP),
 * a Model-as-a-Service framework, API and application suite.
 *
 * 2012-2022, Olaf David and others, OMSLab, Colorado State University.
 *
 * OMSLab licenses this file to you under the MIT license.
 * See the LICENSE file in the project root for more information.
 */
package csip.api.server;

import java.util.Collection;
import org.codehaus.jettison.json.JSONArray;
import org.codehaus.jettison.json.JSONObject;

/**
 * Payload Parameter access.
 *
 * @author od
 */
public interface PayloadParameter {

  /**
   * Check if all parameter exist.
   * @param name the name of the parameter entry
   * @return true if present false otherwise.
   */
  boolean has(String name);


  /**
   * Check if a required parameter exists.
   *
   * @param names the parameter names to check
   * @return this object
   * @throws ServiceException if one or more parameter are not found.
   */
  PayloadParameter require(String... names) throws ServiceException;


  /**
   * Get the number of parameter.
   * @return the number of parameter
   */
  int getCount();


  /**
   * Get all parameter names.
   * @return the set of names.
   */
  Collection<String> getNames();


  /**
   * Get nested payload parameters.
   *
   * @param name the name of the parameter
   * @return the 'sub' parameter set
   * @throws ServiceException if there is no such parameter
   */
  PayloadParameter getParams(String name) throws ServiceException;


  int[] getParamsSize(String name) throws Exception;


  /**
   * Nested Payload parameter at the dimension i.length
   *
   * @param name the parameter name
   * @param i the indices and dims
   * @return the PayloadParameter
   * @throws ServiceException if there is no such parameter.
   */
  PayloadParameter getParams(String name, int... i) throws ServiceException;


  /**
   * Get the entire parameter as JSONObject.
   * @param name the parameter name.
   * @return the parameter JSONObject.
   * @throws ServiceException if there is no such parameter.
   */
  JSONObject getParamJSON(String name) throws ServiceException;


  /**
   * Get a String parameter.
   * @param name the parameter name
   * @return the parameter value as String
   * @throws ServiceException if there is a JSON error.
   */
  String getString(String name) throws ServiceException;


  /**
   * Get a String parameter.
   * @param name the name of the parameter
   * @param def the default value if the parameter is missing
   * @return the value of the parameter
   * @throws ServiceException if there is a JSON error.
   */
  String getString(String name, String def) throws ServiceException;


  /**
   * Get an int parameter.
   * @param name the parameter name
   * @return the parameter value as int
   * @throws ServiceException if there is a JSON error.
   */
  int getInt(String name) throws ServiceException;


  /**
   * Get a int parameter.
   * @param name the name of the parameter
   * @param def the default value if parameter does not exist
   * @return the int value of the parameter.
   * @throws ServiceException if there is a JSON error.
   */
  int getInt(String name, int def) throws ServiceException;


  /**
   * Get an double parameter.
   * @param name the parameter name
   * @return the parameter value as double
   * @throws ServiceException if there is a JSON error.
   */
  double getDouble(String name) throws ServiceException;


  double getDouble(String name, double min, double max) throws ServiceException;


  /**
   * Get a double parameter.
   * @param name the name of the parameter
   * @param def the default value if parameter does not exist
   * @return the double value of the parameter
   * @throws ServiceException if there is a JSON error.
   */
  double getDouble(String name, double def) throws ServiceException;


  double getDouble(String name, double def, double min, double max) throws ServiceException;


  /**
   * Get a boolean parameter.
   * @param name the parameter name.
   * @return the parameter value as boolean.
   * @throws ServiceException if there is a JSON error.
   */
  boolean getBoolean(String name) throws ServiceException;


  /**
   * Get a Boolean parameter.
   * @param name the name of the parameter
   * @param def the default value.
   * @return the boolean value of the parameter.
   * @throws ServiceException if there is a JSON error.
   */
  boolean getBoolean(String name, boolean def) throws ServiceException;


  /**
   * Get a long parameter.
   * @param name the parameter name.
   * @return the parameter value as long.
   * @throws ServiceException if there is a JSON error.
   */
  long getLong(String name) throws ServiceException;


  /**
   * Get a Long parameter.
   * @param name the name of the parameter
   * @param def the default value if parameter does not exist
   * @return the long value of the parameter
   * @throws ServiceException if there is a JSON error.
   */
  long getLong(String name, long def) throws ServiceException;


  /**
   * Get a JSONObject parameter value.
   * @param name the parameter name.
   * @return the parameter value as JSONObject.
   * @throws ServiceException if there is a JSON error.
   */
  JSONObject getJSON(String name) throws ServiceException;


  /**
   * Get a Long parameter.
   * @param name the name of the parameter
   * @param def the default value if parameter does not exist
   * @return the JSONObject of the parameter
   * @throws ServiceException if there is a JSON error.
   */
  JSONObject getJSON(String name, JSONObject def) throws ServiceException;


  /**
   * Get a JSONArray parameter.
   * @param name the parameter name.
   * @return the parameter value as JSONObject.
   * @throws ServiceException if there is a JSON error.
   */
  JSONArray getJSONArray(String name) throws ServiceException;


  /**
   * Get a Long parameter.
   * @param name the name of the parameter
   * @param def the default value if parameter does not exist
   * @return the JSONObject of the parameter
   * @throws ServiceException if there is a JSON error.
   */
  JSONArray getJSONArray(String name, JSONArray def) throws ServiceException;


  /**
   * Get a int[] parameter.
   * @param name the parameter name.
   * @return the parameter value as JSONObject.
   * @throws ServiceException if there is a JSON error.
   */
  int[] getIntArray(String name) throws ServiceException;


  /**
   * Get a int[] parameter.
   * @param name the name of the parameter
   * @param def the default value if parameter does not exist
   * @return the JSONObject of the parameter
   * @throws ServiceException if there is a JSON error.
   */
  int[] getIntArray(String name, int[] def) throws ServiceException;


  /**
   * Get a boolean[] parameter.
   * @param name the parameter name.
   * @return the parameter value as JSONObject.
   * @throws ServiceException if there is a JSON error.
   */
  boolean[] getBooleanArray(String name) throws ServiceException;


  /**
   * Get a boolean[] parameter.
   * @param name the name of the parameter
   * @param def the default value if parameter does not exist
   * @return the JSONObject of the parameter
   * @throws ServiceException if there is a JSON error.
   */
  boolean[] getBooleanArray(String name, boolean[] def) throws ServiceException;


  /**
   * Get a long[] parameter.
   * @param name the parameter name.
   * @return the parameter value as JSONObject.
   * @throws ServiceException if there is a JSON error.
   */
  long[] getLongArray(String name) throws ServiceException;


  /**
   * Get a long[] parameter.
   * @param name the name of the parameter
   * @param def the default value if parameter does not exist
   * @return the JSONObject of the parameter
   * @throws ServiceException if there is a JSON error.
   */
  long[] getLongArray(String name, long[] def) throws ServiceException;


  /**
   * Get a String[] parameter.
   * @param name the parameter name.
   * @return the parameter value as JSONObject.
   * @throws ServiceException if there is a JSON error.
   */
  String[] getStringArray(String name) throws ServiceException;


  /**
   * Get a String[] parameter.
   * @param name the name of the parameter
   * @param def the default value if parameter does not exist
   * @return the JSONObject of the parameter
   * @throws ServiceException if there is a JSON error.
   */
  String[] getStringArray(String name, String[] def) throws ServiceException;


  /**
   * Get a String[][] parameter.
   * @param name the parameter name.
   * @return the parameter value as JSONObject.
   * @throws ServiceException if there is a JSON error.
   */
  String[][] get2DStringArray(String name) throws ServiceException;


  /**
   * Get a String[][] parameter.
   * @param name the name of the parameter
   * @param def the default value if parameter does not exist
   * @return the JSONObject of the parameter
   * @throws ServiceException if there is a JSON error.
   */
  String[][] get2DStringArray(String name, String[][] def) throws ServiceException;


  /**
   * Get a double[] parameter.
   * @param name the parameter name.
   * @return the parameter value as JSONObject.
   * @throws ServiceException if there is no array.
   */
  double[] getDoubleArray(String name) throws ServiceException;


  /**
   * Get a double[] parameter.
   * @param name the name of the parameter
   * @param def the default value if parameter does not exist
   * @return the JSONObject of the parameter
   * @throws ServiceException if there is no array
   */
  double[] getDoubleArray(String name, double[] def) throws ServiceException;


  /**
   * Get the unit of a parameter.
   * @param name the parameter name
   * @return the unit as string, 'null' if there is none.
   * @throws ServiceException if unit is missing
   */
  String getUnit(String name) throws ServiceException;


  /**
   * Get the description of a parameter.
   * @param name the parameter name
   * @return the description as string, 'null' if there is none.
   * @throws ServiceException if there is no description.
   */
  String getDescr(String name) throws ServiceException;


  /**
   * Get the geometry of a parameter.
   * @param name the name if the parameter
   * @return the geometry of a parameter
   * @throws ServiceException if there is no geometry
   */
  JSONObject getGeometry(String name) throws ServiceException;


  /**
   * Get the parameter meta info.
   *
   * @param name the parameter name
   * @param metaKey the meta data key
   * @return the meta data value, or null is there is no key.
   * @throws ServiceException if something goes wrong
   */
  String getMetaInfo(String name, String metaKey) throws ServiceException;


  JSONObject getParam(String name) throws ServiceException;


  JSONObject getParam(String name, JSONObject def) throws ServiceException;

}