With Linxter, one method call does a lot. Under the hood, CreateMessage() and CreateMessages() take care of a lot of complexities.
To get a better idea of how much communication plumbing Linxter takes care of for you, take a walk with us through the life of a message…
The CreateMessage() method call consists of several arguments, of which only one is required:
- Receiver ID — This is the program instance ID (the unique identifier of the program instance) that the message is being sent to (you can use multiple Receiver IDs to send the message to multiple program instances at the same time). Optionally, if this argument is not added or the value is empty (00000000-0000-0000-0000-000000000000), a broadcast message is sent to every program instance that the sending program instance has a communication channel with. Note: The API maintains an up-to-date list of Receiver IDs that your program instance has communication channels with, as well as other related data. This data is available through several simple property calls.
- Activity ID — This identifier is Required. Each program registered to the ISB is assigned an ActivityID, which must be included in any message sent by instances of your program. This ID should be kept secret to protect your account.
- Body — This is the main content of the message. You are not constrained to any specific formatting. The content can be XML, MIME, plain text, a proprietary encoding, or even encrypted cipher text. The Body can be up to 1MB in size.
- File Attachments — Each message can have zero to many attachments, either as attachment paths to files or as objects (binary resources).
- Message Tracking (Non-repudiation) — If enabled, your program instance will receive a notification of the date/time the message was picked-up by the receiving program instance(s).
- Priority — Messages are delivered in priority order, and sorted by creation time within a priority. Priority 0 is the default. Higher priorities will be delivered before messages with a lower priority value. You can use this property to allow messages to be bumped ahead of previously queued messages by raising the priority of them.
- SendViaSecondaryQueue — The secondary outbound queue runs on its own thread, and can send concurrently with the primary outbound queue. You can use the secondary outbound queue, for example, when the primary is sending lots of short messages that need to arrive to their recipients quickly, and the secondary for sending messages with attachments which would take longer to send, and would otherwise block the shorter messages sent afterwards.
- Tags — Optional labels you can add to the message. They can be used to represent the content of the message envelope, the use or operation the message is intended for, or for any other purpose.
When the CreateMessage() method call is made, the message is placed in the API’s encrypted managed queue, and then security and validation checks are performed. Neither the API nor the Internet Service Bus (ISB) reviews the content of the message Body or Attachments, except for determining size.
After the security and validation checks, the local encrypted managed API queue then sends the message…
… or messages either based on an event or based on a schedule.
Sending and receiving messages is asynchronous and non-blocking to your program. This means your program instance can keep on doing what it is doing and not worry about getting hung while processing a send or receive operation. This is true regardless if done via the on-demand method calls or if scheduled intervals are used.
On-demand
In your code, you can send and receive on-demand using the SendNow() and ReceiveNow() method calls.
ReceiveNow() will not be fired when called if there is not a subscription to the MessageReceivedEvent.
Scheduled Sending and Receiving
Sending
Scheduled sending is automatically enabled when your program instance is running. Your instance will only try to send a message if there is one or more waiting to be sent in your local queue.
Receiving
Scheduled receiving is automatically enabled when your instance is running and there is a subscription to the MessageReceivedEvent.
Fixed or Range Interval
The schedule can be a fixed time interval, or an allowed range which an instance can choose from (either programmatically or via a user interface control). The settings for these events can be dynamically updated through Web Manager.
Now, the API connects to the ISB. All of the ISB service points are load-balanced and geographically redundant. If your program is trying to send messages but is experiencing a temporary loss of Internet connectivity, then the API automatically enters into a retry mode and connects once the issue is resolved.
The API connects to the ISB … the API authenticates itself, and commences sending one or more messages.
All messages are encrypted using X.509 certificates. This provides for end-to-end security, regardless of the number of intermediaries involved in transferring the message and regardless of whether or not the transport is secure.
Linxter cloud messaging uses flat transactions, also known as a two-phase commit process, from end-point to end-point. For example, when a program instance creates a message, it is stored in a local, encrypted queue (written to disk), until the message has been successfully transferred to the ISB. The message is not removed from the queue until it has been verified that is was received intact by the ISB.
If your program is trying to send or receive messages but is experiencing a temporary loss of Internet connectivity, then the API automatically enters into a retry mode and connects to the ISB once the issue is resolved.
With assured information delivery, a core feature of Linxter, even if your program instance loses its network connection during the sending or receiving of a message, or if another failure interrupts the process, the transaction resumes with the message intact whenever the issue is resolved.
Another reliability and efficiency feature built into Linxter is chunking. For example, let’s say you are sending a message with a 10MB file attachment, and after transmitting 7MBs, the sending program loses its Internet connection. When the connection is re-established, the process picks up from where it left off. Reliability features like this are especially important with wireless (and its frequent interruptions in connectivity) becoming the norm.
The ISB, upon verified receipt of a message, performs security and validation inspections. Among the steps, the ISB verifies that communication channels between the sending program instance and the receiving program instances exist. Once verified, messages are placed in their assigned outbound queues, where they wait to be picked up by their receiving program instances. The outbound queues are load balanced as well as geographically redundant.
For the program instances receiving the messages, the same security and reliability features apply.