Updating items in a single-row agent

In this Lesson

You will

  • Learn how single-row agents process change mode
  • Learn the importance of keys for agents
  • Understand the relationship between keys and context
  • Modify the solution to allow parties to be modified


Agents can be thought of as Java objects representing some portion of the emergent data model. When a context key is published into the conversation agents load their scheme with the portion of the data model they represent. When agents load their scheme they also store the unique key of the information being loaded. The agent’s key values serve two purposes

  1. The key informs the pump about the contents of the agent’s scheme.
    If the keys are absent (null) this indicates the agent does not currently contain any information related to the current context. If the keys are present (a non-null value) this indicates the agent does contain information related to the specified key.
    Big Brother is Watching
    The pump compares the current context against the agent keys. When the pump pushes a subscribed to an agent it expects one of two things. 1) The agent sets it keys to null – indicating it could not find anything related to the key and therefore is offering no data or 2) the agent sets its key to match the subscribed value coming from the pump. If the agent sets its key to any other value the pump will stop the conversation and emit an error describing the offending agent.
  2. The key serves as a pointer back into the data source.
    When an agent needs to write changes back to the data source it uses the agent key to locate the database row that should be updated.

The agent’s keys are defined in the Context Value section as shown here

Keys and Context

The agent sets its key by calling one of the setKey…() methods on the scheme.
The agent publishes context values by calling one of the setContext…() methods on the scheme.

If the agent’s key values are also declared as published values then the scheme’s setKey… methods will also publish the value. This eliminates the need to call both the setKey…() and setContext…() methods when updating the agent key.

Modify the solution to update a party definition

In this exercise you will provide the ability to modify an existing party definition. You will be playing the designer role – because the agent that we need to update a party has already been created.

  1. Open the PartyDefinition scene
  2. Make a copy of layer 4 (the view layer)

  3. Name the new thumbnail change

  4. Switch to the agent binding perspective and set the PartyTheme agent’s mode to change

  5. Set the Party agent’s mode to change

  6. Modify the change layer to make it appropriate for change processing
    • Switch to the design perspective for the change layer
    • Remove the Retain Host Information checkbox
    • Add a Cancel button and center the OK and Cancel buttons in the container

    • Right click the Cancel button and configure it to close the change layer

  7. Select the view layer
  8. Make the view layer a better example of a view-only container.
    It is not good practice to present view-only information in elements designed for data input.
    Also, the Retain Host Information checkbox does not apply to view mode.
    • Remove the Retain Host Information checkbox
    • Replace the date picker element with a Data: Single Line element

    • Replace the time selection elements with Data: Single Line elements
    • Hold down the Control key and left click the 2 time display elements. They should both appear selected as shown here

    • Right click on one of the selected elements to display a property sheet. Notice the property sheet is modifying 2 Text Value elements and all of the properties are blank. Change the Value Presentation to Show Code List Description and press OK. The property sheet will apply the change to both elements.

    • Replace the party type element with a Data: Single Line element
    • Right click on the party type element to open its property sheet and change the Value Presentation to Show Code List Description and press OK.

    • Replace the location element with a Data: Multi Line element
    • Replace the remaining text field elements with a Data: Single Line element
      The view layer should now look like this

    • Add a hyperlink element in the upper right corner
    • Right click the hyperlink element to open its property sheet.
    • Change the Text value to Edit and configure it to open the change layer

    • Resize the element to fit its text and the view layer should now look like this

  9. Switch to the Agent binding perspective for the view layer.
  10. Rebind the Party and PartyTheme agents to the layer
    All of the elements should have a color showing they are bound to the proper agent

  11. Save the scene
Test the solution
  1. Start the solution
  2. Advance to the party list
  3. Select a party
    Ensure all of the values display correctly in the view layer

  4. Press the Edit link in the upper right corner of the view layer. The change layer should appear

  5. Change the party name and press OK. The change layer should close and the new party name should appear in both the party list and the party details.

Congratulations! You now have full add, change, delete capability working for a party.

It is either time to hurry off to the next lesson or take a moment and bask in your success.