//===========================================================================
  //     Create a Standardized InternalKQMLmessage for CommPeer users.
  //===========================================================================

  //---------------------------------------------------------------------------
  // The Communicator implements the CommunicationInterface which requires that
  // agent messages adhere to "Communicator.AgentMsg" format.  "AgentMsg"
  // format, in turn enforces a particular interpretation of KQML.  This method
  // captures that interpretation, and should be used to generate "safe"
  // Communicator messages. 
  //
  // N.B.:  The default InternalKQMLmessage initializations are particular to
  // CommPeer use, hence their inclusion in this class and not in
  // InternalKQMLmessage.
  //---------------------------------------------------------------------------
  public static InternalKQMLmessage createInternKQMLMsg
    (String perf_str, String who_I_am, String agentName, String message,
     String reply_with, String in_reply_to, String lang_str, String onto_str) {

  //---------------------------------------------------------------------------
  // A version of "createInternKQMLMsg()" which prefers that the caller
  // specify:  PERFORMATIVE, SENDER, RECEIVER, and CONTENT.
  //---------------------------------------------------------------------------
  public static InternalKQMLmessage createInternKQMLMsg
    (String perf_str, String who_I_am, String agentName, String message) {

  //---------------------------------------------------------------------------
  // A version of "createInternKQMLMsg()" which prefers that the caller
  // specify:  SENDER, RECEIVER, and CONTENT.
  //---------------------------------------------------------------------------
  public static InternalKQMLmessage createInternKQMLMsg
    (String who_I_am, String agentName, String message) {


  //---------------------------------------------------------------------------
  // A version of "createInternKQMLMsg()" which prefers that the caller
  // specify:  RECEIVER and CONTENT.
  //---------------------------------------------------------------------------
  public static InternalKQMLmessage createInternKQMLMsg (String agentName,
                                                         String message) {

  //---------------------------------------------------------------------------
  // A version of "createInternKQMLMsg()" which prefers that the caller
  // specify:  RECEIVER.
  //---------------------------------------------------------------------------
  public static InternalKQMLmessage createInternKQMLMsg (String agentName) {


  //===========================================================================
  //               :CONTENT Field Value Convenience Methods
  //===========================================================================

  //---------------------------------------------------------------------------
  // A boolean function that will treat "null", the empty string (""), strings 
  // with any length of whitespace ("  "), strings with nested levels of
  // parentheses "(())", and malformatted KQMLmessage strings "(:field value)" 
  // as if they were empty KQMLmessages.
  //---------------------------------------------------------------------------
  public static boolean isEmptyKQMLmessageP (String content) {

  //---------------------------------------------------------------------------
  //                 Any InternalKQMLmessage to Any Agent
  //
  // Sometimes it is convenient that the :CONTENT of an InternalKQMLmessage be
  // parseable as a KQMLmessage.  This is ideal if the entity that will read
  // the message knows exactly which fields to access.  This technique is not
  // advantageous if there can be an arbitrary number of fields with different
  // names.
  //
  // This method returns a string which is intended to be assigned to the
  // :CONTENT field of an InternalKQMLmessage.
  //---------------------------------------------------------------------------
  public static String makeKQMLMsgContentString (KQMLmessage content) {

  //---------------------------------------------------------------------------
  //                 Any InternalKQMLmessage to Any Agent
  //
  // Sometimes it is convenient that the :CONTENT of an InternalKQMLmessage be
  // parseable as a KQMLmessage.  This is ideal if the entity that will read
  // the message knows exactly which fields to access.  This technique is not
  // advantageous if there can be an arbitrary number of fields with different
  // names.
  //
  // This method takes an array of pairs (eg. {{:field1 value} {field2 value}})
  // and converts it into an object of type KQMLmessage.
  // The performative is the class constant, CONTENT_PERFORMATIVE.
  //---------------------------------------------------------------------------
  public static KQMLmessage makeKQMLMsgContent (String[][] field_value_pairs) {


  //---------------------------------------------------------------------------
  //                 Any InternalKQMLmessage to Any Agent
  //
  // This method allows the user to specify a PERFORMATIVE other than the
  // CONTENT_PERFORMATIVE. 
  //---------------------------------------------------------------------------
  public static KQMLmessage makeKQMLMsgContent (String performative_name,
                                                String[][] field_value_pairs) {


  //---------------------------------------------------------------------------
  //               Any InternalKQMLmessage to Any InfoAgent
  //
  // Use this method for composing InfoAgent query :CONTENT fields.
  //---------------------------------------------------------------------------
  public static String makeInfoAgentQueryContent (String key) {


  //===========================================================================
  //    Wrap / Unwrap Value Fields that Are *NOT* in KQMLmessage format
  //===========================================================================

  //---------------------------------------------------------------------------
  // If the value of a KQML message's :CONTENT field (or conceivably any other)
  // has multiple cardinality, that is, a string of space-separated tokens, it
  // *MUST* be wrapped in parentheses or the KQMLParser will misinterpret those
  // values as part of the KQML message itself.
  // 
  // Call this method with "val_str" set to the value of the :CONTENT field.
  // The return value will be a string without its parenthetical wrapper.
  //
  // N.B.:  If "val_str" represents a KQMLmessage and you would like direct
  // access to "val_str"'s fields/value pairs, call "new KQMLmessage(val_str);"
  // instead.
  //---------------------------------------------------------------------------
  public static String unwrapValue (String val_str) {

  //---------------------------------------------------------------------------
  // If the value of a KQML message's :CONTENT field has multiple cardinality,
  // that is, a string of space-separated tokens, it *MUST* be wrapped in
  // parentheses or the KQMLParser will misinterpret those values as part of
  // the KQML message itself.
  // 
  // Call this method to "wrap" "val_str" in parentheses so that it may be
  // transmitted as the value for a InternalKQMLmessage's :CONTENT field.
  // The return value will be a "val_str" within a parenthetical wrapper.
  //
  // If "val_str" is null, then the value of NULL_MSG, above, is returned in
  // parentheses.
  //
  // N.B.:  Do *NOT* call this method if "val_str" was created by
  // "makeKQMLMsgContentString()", above.
  //
  // Implementation note:  no checking is performed on the first or last
  // characters of "val_str", as its value may be: "(token1) (tokenN)".
  //---------------------------------------------------------------------------
  public static String wrapValue (String val_str) {