package nxm.sys.inc;

/**
  Interface Definitions for key accessible Objects.

  These methods allow access to methods or fields of an object by name.
  This requires writing a branch of code for each desired access, but
  is quicker than the {@link nxm.sys.lib.KeyObject} class; and is necessary
  to access members of a collection (e.g. {@link nxm.sys.lib.KeyObject},
  {@link nxm.sys.lib.Table}) from within a NeXtMidas macro. It should only
  be used for NeXtMidas specific high-traffic objects (e.g.
  {@link nxm.sys.lib.Message} and {@link nxm.sys.lib.Data}.

  @see nxm.sys.lib.KeyObject

  @author Jeff Schoen
  @version $Id: Keyable.java,v 1.9 2014/10/21 18:29:58 ntn Exp $
*/
public interface Keyable {

  /** Get the value of an object's keyed field.

      @param key  The key identifying the value.

      @return The value associated with the key.
      @todo Explain what happens if the key is undefined.
   */
  Object getKey (String key);

  /** Set the value of an object's keyed field.

      @param key   The key identifying the value.
      @param value The new value to associate with the key.

      @return The specified value (<code>value</code>) or the value that would be returned by {@link #getKey(String)}
              immediately after this method call. Since there can be some ambiguity the return value here should
              probably be ignored.
   */
  Object setKey (String key, Object value);

  /** Get a list of the available keys.

      @return An array of Strings holding the key names.
   */
  String[] getKeys ();

}
