Before You Start Coding

Before you can incorporate the Messaging Toolkit functionality into your application, you need to determine the way that your tool will work with other tools. There are several basic questions you need to ask:

1. How will these tools work together?

2. What kinds of operations can these tools perform?

3. What kinds of operations can these tools ask other tools to perform?

4. What events will these tools generate which may interest other tools? (What types of messages will these tools want to send?)

5. What events generated by other tools will be of interest to these tools? (What types of messages will these tools want to receive?)

To best answer these questions, you need to understand the difference between events and operations, and how the ToolTalk service handles messages regarding each of these.

What Is the Difference Between an Event and an Operation?

An event is an announcement that something has happened. An event is simply a news bulletin. The sending process has no formal expectations as to whether any other process will hear about the event, or whether an action is taken as a consequence of the event. When a process uses the ToolTalk service to inform interested processes that an event has occurred, it sends a notice. Since the sending process does not expect a reply, an event cannot fail.

An operation is an inquiry or an action. The requesting process makes an inquiry or requests that an operation be performed. The requesting process expects a result to be returned and needs to be informed of the status of the inquiry or action. When a process uses the ToolTalk service to ask another tool to perform an operation, it sends a request. The ToolTalk service delivers the request to interested processes and informs the sending process of the status of the request.

Sending Notices

When your application sends a ToolTalk notice, it will not receive a reply or be informed about whether or not any tool pays attention to the notice. It is important to make the notice an impartial report of the event as it happens.

For example, if your tool sends the Desktop Services message Modified, it may expect any listening tools to react in a given way. However, your tool should not care, and does not need to be informed, about whether any or no other tool reacts to the message; it only wants to report the event:

THE_USER_HAS_MADE_CHANGES_TO_THIS.

Sending Requests

When your application sends a ToolTalk request, it expects one tool to perform the indicated operation, or to answer the inquiry, and return a reply message. For example, if your tool sends the Desktop Services message Get_Modified, it should expect notification that the message was delivered and the action performed. The ToolTalk service guarantees that either a reply will be returned by the receiving process or the sender will be informed of the request's failure.

You can identify requests in three ways:

1. By identifying the operations requested by your tool that can fail

2. By identifying the operations your tool can perform for other tools

3. By identifying the operations your tool will want other tools to perform

A good method to use to identify these operations is to develop a scenario that outlines the order of events and operations that you expect your tool to perform and have performed.

Developing a Scenario

A scenario outlines the order of the events and operations that a tool will expect to perform and have performed. For example, the following scenario outlines the events that the ToolTalk demo program CoEd expects to perform and have performed:

1. User double-clicks on a document icon in the File Manager.

   The file opens in the editor, which is started by the system if one is not already running.

   If another tool has modifications to the text pending for the document, User is asked whether the other tool should save the text changes or revert to the last saved version of the document.

2. User inserts text.

3. User saves the document.

   If another tool has modifications pending for the document, User is asked whether to modify the document.

4. User exits the editor.

   If text has unsaved changes, User is asked whether to save or discard the changes before quitting the file.

Once the scenario is done, you can answer your basic questions.

How Will the Tools Work Together?

• The File Manager will request that CoEd open a document for editing.

• Each instance of CoEd will notify other interested instances of changes it makes to the state of the document.

What Kinds of Operations Do the Tools Perform?

• Each instance of CoEd can answer questions about itself and its state, such as "What is your status?"

• Each instance of CoEd has the capability of performing operations such as:

  • Iconifying and de-iconifying

  • Raising to front and lowering to back

  • Editing a document

  • Displaying a document

  • Quitting

What Kinds of Operations Can the Tools Ask Other Tools to Perform?

• The File Manager must request that CoEd open a document for editing.

• An instance of CoEd can ask another instance of CoEd to save changes to the open document.

• An instance of CoEd can ask another instance of CoEd to revert to the last saved version of the open document.

What Events Will the Tools Generate That May Interest Other Tools?

• The document has been opened.

• The document has been modified.

• The document has been reverted to last saved version.

• The document has been saved.

• An instance of CoEd has been exited.

What Events Generated by Other Tools Will Be of Interest to This Tool?

• The document has been opened.

• The document has been modified.

• The document has been reverted to last saved version.

• The document has been saved.

• An instance of CoEd has been exited.