//=========================================================================== // 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) {