package nxm.sys.inc;

import nxm.sys.lib.Args;
import nxm.sys.lib.Command;
import nxm.sys.lib.Message;
import nxm.sys.lib.Midas;

/** Defines the interface for a <code>CommandParent</code> that oversees the execution of a command.


    @author  J. Czechowski IV
    @since   NeXtMidas 2.1.0
*/
public interface CommandParent {
  /** Pre-processes the arguments for a command. The noop version of this method is:
      <pre>
        public Args setArgs(Command cmd, Args args) { return args; }
      </pre>
      @param cmd  The command.
      @param args The arguments passed to the command.

      @return The pre-processed args to be set by {@link Command}.
   */
  Args setArgs(Command cmd, Args args);

  /** Called when the command enters the {@link Command#run()} method (but after
      {@link Command#checkin(Midas)} has been called). The noop version of this method is:
      <pre>
        public void runEnter(Command cmd) { }
      </pre>
      @param cmd The command.
   */
  void runEnter(Command cmd);

  /** Called when the command exits the {@link Command#run()} method (but before
      {@link Command#checkout()} has been called). The noop version of this method is:
      <pre>
        public void runExit(Command cmd) { }
      </pre>
      @param cmd The command.
   */
  void runExit(Command cmd);

  /** Called by {@link Command#run()} to perform each pass in the processing loop.
      The default version of this method is:
      <pre>
        public void runSingle(Command cmd) { return cmd.runSingle(); }
      </pre>
      @param cmd      The command.
      @param state    The current command state.
      @param setState The command state to switch to in {@link Command#runSingle()}.
      @return The updated status.
   */
  int runSingle(Command cmd, int state, int setState);

  /** Processes messages from the message queue. The default version of this method is:
      <pre>
        public int processMessages(Command cmd, int maxmsg) {
          return cmd.processMessages(maxmsg);
        }
      </pre>
      @param cmd    The command.
      @param maxmsg The maximum number of messages to process from the queue or -1 to process all
                    available messages.
      @return The status returned from processing the last message with
              {@link Command#processMessage(Message)} or {@link Command#NOOP} if no messages
              have been processed.
      @see Command#processMessage(Message)
   */
  int processMessages(Command cmd, int maxmsg);
} // end interface CommandParent
