Using messages to transfer information between systems or functions

12th April 2016

Filed under: Best Practices, Featured
Comments: None

A message (Transfer Object) contains a unit of information with a message as its root and a hierarchy of messages, collections of messages, or primitive values (where primitive values are defined by a pair consisting of a named attribute with a value for the primitive). This message can be passed to another function or system.

For example, a message can be used to transfer information from a source database to a destination database on a completely different platform. Also, you can use a message to send heterogeneous information to functions that may need to handle varied input or messages.

Messages support operations to set and get values in the message, test if a message contains a value, an operation to remove values or sub-messages, and an iterator of sub-messages.

Message example

(define m (message (: a "A") (: b 2) (: c (message)) (: d (collection (message)))))

(m'a) => "A"
(m'b) => 2
((m'c)'z) => ()
((m'x)'z) => ()
((m'd)'size) => 1
(m'b 3) => 3
(m'b) => 3;
(m':contains 'd) => #t
(m':contains "d") => #t
(m':remove 'b) => #t
(m':remove 'b) => #f

(define m (message (: a "A") (: b 2) (: c (message)) (: d (collection (message)))))

(m'a) => "A"

(m'b) => 2

((m'c)'z) => ()

((m'x)'z) => ()

((m'd)'size) => 1

(m'b 3) => 3

(m'b) => 3;

(m':contains 'd) => #t

(m':contains "d") => #t

(m':remove 'b) => #t

(m':remove 'b) => #f

Using a message to create a new instance

The following is an example of message passed to the ‘new function which will create a new instance based on the attributes defined in the message. This message creates a progressed opportunity with a specific template, user, and parent opportunity.

(let
   ((newOppty (ProgressedOpportunity'new
  (: template template)
  (: owner ((user)'person))
  (: expectedRevenue (parentOppty'expectedRevenue))
  (: expectedCloseDate (parentOppty'expectedCloseDate))
  (: priority (parentOppty'priority))
  (: text (parentOppty'text))
  args)
   ))
   ; return
   newOppty
)

(let

((newOppty (ProgressedOpportunity'new

(: template template)

(: owner ((user)'person))

(: expectedRevenue (parentOppty'expectedRevenue))

(: expectedCloseDate (parentOppty'expectedCloseDate))

(: priority (parentOppty'priority))

(: text (parentOppty'text))

args)

))

; return

newOppty

)

Using a message to send heterogeneous information and then iterate through the sub-messages

This is an example of a message with a collection of heterogeneous messages to create filter rule subject areas. The message defines the subject areas to create with their supplied attributes. An iterator is used to read each subject area message and then build a new instance accessing the messages attributes similar to the previous example.

(set! defaultSubjectAreas
   (message
      (: TEST_PSN
         (message
            (: defaultCaption "Contacts")
            (: clause '(and (instance? (@) Person) (not (and (instance? (@) UserPerson) (@ isUser)))))
            (: filterType (read-instance FilterRuleType '() '(= (@ name) "TEST_CONTACT") #f))
         )
      )
      (: TEST_CO
         (message
   (: name "Test Subject Area - Companies")
            (: defaultCaption "Companies")
            (: clause '(instance? (@) Company))
            (: icon "company")
            (: filterType (read-instance FilterRuleType '() '(= (@ name) "TEST_CONTACT") #f))
         )
      )
   )
)

(for-each
   (lambda (subjectAreaName)
      (let (
              (subjectArea (defaultSubjectAreas subjectAreaName))
              (frSubjectArea (read-instance FilterRuleSubjectArea '() `(= (@ name) ,subjectAreaName) #f))
           )
         (cond
            ((null? frSubjectArea)
               (set! frSubjectArea
                  (FilterRuleSubjectArea'new
                     (: name 
         (if (null? (subjectArea'name))
 						   subjectAreaName
                          (subjectArea'name)
       )
         )
                     (: defaultCaption (subjectArea'defaultCaption))
                     (: clauseString ((subjectArea'clause)'toString))
                     (: icon (subjectArea'icon))
                     (: filterType (subjectArea'filterType))
                  )
               )
            )
            (else
               (frSubjectArea'clauseString ((subjectArea'clause)'toString))
            )
         )
         (defaultSubjectAreaHash'put (frSubjectArea'name) frSubjectArea)
      )
   )
   (defaultSubjectAreas':iterator)
)
(commit)

(set! defaultSubjectAreas

(message

(: TEST_PSN

(message

(: defaultCaption "Contacts")

(: clause '(and (instance? (@) Person) (not (and (instance? (@) UserPerson) (@ isUser)))))

(: filterType (read-instance FilterRuleType '() '(= (@ name) "TEST_CONTACT") #f))

)

(: TEST_CO

(message

(: name "Test Subject Area - Companies")

(: defaultCaption "Companies")

(: clause '(instance? (@) Company))

(: icon "company")

(: filterType (read-instance FilterRuleType '() '(= (@ name) "TEST_CONTACT") #f))

)

(for-each

(lambda (subjectAreaName)

(let (

(subjectArea (defaultSubjectAreas subjectAreaName))

(frSubjectArea (read-instance FilterRuleSubjectArea '() `(= (@ name) ,subjectAreaName) #f))

)

(cond

((null? frSubjectArea)

(set! frSubjectArea

(FilterRuleSubjectArea'new

(: name

(if (null? (subjectArea'name))

subjectAreaName

(subjectArea'name)

)

(: defaultCaption (subjectArea'defaultCaption))

(: clauseString ((subjectArea'clause)'toString))

(: icon (subjectArea'icon))

(: filterType (subjectArea'filterType))

)

(else

(frSubjectArea'clauseString ((subjectArea'clause)'toString))

)

(defaultSubjectAreaHash'put (frSubjectArea'name) frSubjectArea)

)

(defaultSubjectAreas':iterator)

)

(commit)

Using a message to transfer a table from one database to another

The databases can be different versions of the same type, or two different types of databases, for example Oracle and DB2.

Essentially, two functions are required.

The first function generates a message based on the rows of the table in the original database.

(set! rowMessages
   (message
   (collection
         (message
         (: firstName "Bill")
         (: lastName "Smith")
            (: age 42)
      )
         (message
         (: firstName "Jane")
         (: lastName "Jones")
      )
      )
   )
)

(set! rowMessages

(message

(collection

(message

(: firstName "Bill")

(: lastName "Smith")

(: age 42)

)

(message

(: firstName "Jane")

(: lastName "Jones")

)

The second function is used to perform any transformations needed by the receiving database. In this example, the first database does not require an age but the second database does. We will make a transformation function to read a row message and, if there is no age, set the value to a default value of -1 to meet the requirement.

(for-each
   (lambda (rowMessage)
      (let*
         (
      (row (rowMessages rowMessage))
   (newMsg
      (message
         (: firstName (row'firstName))
         (: lastName (row'lastName))
      (if (null? (row'age))
         (: age -1)
                     (: age (row'age)					 
      )
      )
   )
   )
      (insert-database-row newMsg)
      )
   )
   (rowMessages':iterator)
)
(commit)

(for-each

(lambda (rowMessage)

(let*

(

(row (rowMessages rowMessage))

(newMsg

(message

(: firstName (row'firstName))

(: lastName (row'lastName))

(if (null? (row'age))

(: age -1)

(: age (row'age)

)

(insert-database-row newMsg)

)

(rowMessages':iterator)

)

(commit)

Message example

Using a message to create a new instance

Using a message to send heterogeneous information and then iterate through the sub-messages

Using a message to transfer a table from one database to another

Your feedback