/*
 * $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;

/**
 * Payload Metainfo access.
 *
 * @author od
 */
public interface PayloadMetaInfo {

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


   String getString(String name, String def);


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


   String[] getStringArray(String name, String[] def);


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


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


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


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


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


   boolean getBoolean(String name, boolean def);


  /**
   * Check if a metainfo entry exists.
   * @param name the name of a metainfo name.
   * @return true if a metainfo entry exists, false otherwise
   */
   boolean hasName(String name);


  /**
   * Check is a required key exists.
   *
   * @param names the parameter name
   * @return this object
   * @throws ServiceException if the parameter is not found.
   */
   PayloadMetaInfo require(String... names) throws ServiceException;


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


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


  /**
   * Set a warning message.
   *
   * @param msg the message
   * @throws ServiceException if warning cannot be added.
   */
   void setWarning(String msg) throws ServiceException;


   void put(String key, String value) throws ServiceException;


   void put(String key, int value) throws ServiceException;


   void put(String key, long value) throws ServiceException;


   void put(String key, double value) throws ServiceException;


   void put(String key, String[] value) throws ServiceException;


  /**
   * Append a warning.
   *
   * @param msg the message to append
   * @throws ServiceException if json operation fails
   */
   void appendWarning(String msg) throws ServiceException;

}