The Protocol Editor tool is used to modify the state diagram and roles that are associated with a particular protocol. The Protocol Editor provides a a dialog for creating and modifying roles, a drawing canvas for graphically defining states and transitions and a dialog for viewing the protocol's state table.
The Protocol Editor contains a menu bar with file items: File , Edit , Diagram , Windows and Help . The File menu allows you to open protocols and save the current protocol. You can also save the protocol description to a file. The File menu also allows you to close the Protocol Editor and shut down AgentBuilder. The Edit menu allows you to cut, copy, and paste states. Using the Delete menu item you can delete states and transitions. The Diagram menu allows you to modify the current state diagram by adding new states or transitions. The dialogs for viewing the state table and the roles can also be accessed using the Map menu items. The Map menu also provides menu items for clearing the state diagram and refreshing the display. A sample state diagram is shown in Figure 73.
Figure 73. State Diagram
You can create a new state by right-clicking on an unoccupied region of the state diagram and selecting New State from the pop-up menu. This will display the state properties dialog that will allow you to enter a name, description, and state type. The state properties dialog is shown in Figure 74. The state type provides a graphical way of indicating which state is the initial state, which states are final states, and which states are normal states. Only one state is allowed to be an initial state. You will receive an error dialog if you attempt to set more than one state as an initial state. The tool doesn't require you specify an initial and final state. The state types provide a graphical enhancement of the state diagram view. Clicking the OK button will create a new state on the state diagram. This state is represented by a circular node with the state's name as its label. Note that the point on the state diagram where you right-click is the location where the state is placed. If you decide not to create a new state, you can click on the Cancel button and the state diagram will remain unchanged. You can also use the Map menu to create a new state in a similar manner.
Figure 74. State Properties Dialog
States can be cut, copied, or pasted. There are two ways to use the clipboard functions for a concept. The first way is to use the Edit menu's Cut , Copy and Paste menu items. The other method is to use the state node's pop-up menus for cut and copy, and the Map's pop-up menu for paste. Whichever method is used, a state must first be selected before a cut or copy operation. If the map being pasted into already contains the name of the state being pasted, the state being pasted will recursively have CopyOf prepended to its name.
You can create a new transition by right-clicking on any unoccupied region of the state diagram and selecting the New Transition menu item. Once selected, the cursor will change to a cross-hair cursor and you can then click on the starting state and drag the cursor to the ending state. Once a valid starting state and ending state have been selected, the Transition Properties dialog will be displayed as shown in Figure 75. The Properties Dialog allows you to specify a name for the transition and an optional description.
Figure 75. Transition Properties Dialog
The rest of the dialog allows you to specify the KqmlMessage that is used in the transition. The required KQML fields are the sender , receiver , performative , ontology , and content type . Since the sender and receiver fields are required, you must first have some roles defined before you can create any transitions. If no roles exists, you will see an error when trying to create a new transition (See Creating Roles below). Selecting an ontology will also load the selected ontology's objects into the Content Type combo box. For the content field, you can only enter a value if the selected content type is a Java primitive type. Entering a new values into the Reply-With combo box will automatically add the new entry to the In-Reply-To combo box. All entries will then be saved when the protocol is saved so that for any new transitions created, they will have the list of all Reply-With entries added.
Clicking on OK will add the transition between the selected states. An arrowhead will be drawn with the arrow pointing towards the ending node. Clicking on Cancel will cancel the creation of the new transition.You can freely move a state node anywhere on the state diagram. This can be done by clicking on the desired state node and dragging the node to a new location. Transitions will adjust themselves automatically to maintain the connection with the relocated state.
You can move multiple states at a time. First, select the states you wish to move. To do this, hold the Control key down and select the states using the mouse. Once you have a group of states selected, hold the Control key down and drag one of the selected states to a new location. You will notice that all the selected states will move in relation to the mouse cursor. To deselect the states, simply click on the canvas.
You can delete an existing state node by clicking on that node and selecting Delete from the pop-up menu. Likewise, a selected state can be deleted using the Delete item in the Edit menu. Note that when a state is deleted, all links to that state are also deleted.
You can delete an existing transition by selecting the transition and selecting Delete from the pop-up menu. You can also select Delete from the Edit menu with a selected transition.
You can view and modify the name, description and type of an existing state by selecting Properties... from the state's pop-up menu. The state properties dialog will then be shown, and you can modify any or all of the state's properties. Clicking on OK will commit any changes that you have made to the state. Clicking on Cancel will revert the state to its original properties.
You can view and modify the name, description and KqmlMessage fields of an existing transition by selecting Properties... from the state's pop-up menu. The Transition Properties dialog will then be shown, and you can modify any or all of the transition's properties. Clicking on OK will commit any changes that you have made to the state. Clicking on Cancel will revert the state to its original properties.
The state table is generated from the transitions in the state diagram. If you currently have no transitions created, you will be given an error dialog and the state table dialog will be shown. Otherwise, the state table dialog will appear as shown in Figure 76. The state table dialog lets you see the important KQML message fields for each transition: sender , receiver , performative , content type and content . There is a combo box for selecting which role to view the state table. Currently, only the All Roles selection is supported.
Figure 76. State Table Dialog
To view the roles that this protocol is using, select the Diagram < Roles... menu item. This will display the Roles Dialog as shown in Figure 77. The Roles Dialog has two panels: the left panel lists the defined roles, and the right panel gives a description of a selected role in the left panel. This dialog also contains a menu bar with a File and Edit menu. The File menu allows you to create a new role, and to close the dialog. The Edit menu gives you cut, copy, paste, and delete functions for the role. The Edit menu also allows you to bring up the properties dialog for a selected role.
Figure 77. Roles Dialog
Roles need to be created so that you can create transitions. To create a new Role, select the File->New menu item. The Role Properties dialog will be displayed and will allow you to specify the new role's properties. The Role Properties dialog is shown in Figure rolePropertiesDialog. The dialog will allow you to specify a name, description and instance number for the role. The instance number is specified by selecting the Instance combo box. The combo box is an editable combo box so that you can enter an integer number to specify the maximum number of instances allowed for the role.
The Edit menu items will allow you to cut, copy and paste roles. To cut or copy a role, you must first select the role from the left panel, then select Copy or Paste from the Edit menu. To paste a role that has been cut or copied to the clipboard, select the Paste menu item from the Edit menu. The role will then be added to the list of roles in the left panel. If a role in the list already has the name of the role being pasted, the pasted role will recursively have CopyOf prepended to its name until it is unique.
To delete a role from the list, you must first select the role, then select Edit < Delete . A confirmation dialog will be shown before the role is actually deleted. Once deleted, the role is removed from the list.
To view a role's properties, you must first select the role in the list, then select Edit < Properties . The Role Properties dialog will then be displayed showing the selected role's properties. Once the dialog is displayed, you can modify any or all of the roles properties. Clicking on OK will commit changes made to the role's properties. Clicking on Cancel will cancel any changes that have been made to the role.
You can save a state diagram by selecting Save under the File menu. You can then close the Protocol Editor and return to it at a later time. The save action will save the states and transitions as well as their locations relative to each other.
The state diagram can be saved to a text file by selecting File < Generate Printable . Selecting this menu item will bring up a file dialog for saving a state diagram to a file. By default, the directory is set to the current working directory, and the filename is set to protocol-name.txt . The text file that is generated will contains a text description of the protocol's name and description as well as a description of every state and transition that make up the protocol.
If you wish to delete everything on the current state diagram and start again, you can do so by selecting Clear under the Diagram menu item or from the state diagram's pop-up menu. Note that this function will remove all states and transitions that have been entered. You will be presented with a confirmation dialog before actually clearing the state diagram. If you later decide that you liked the original state diagram and you have not yet saved the changes, you can just close the Protocol Editor or reload the Protocol Editor using the File < Open menu item.