How To Build An Agent

An agent is created and managed by the container. Building an agent is done in two steps:

• Write Agent code
• Declare the agent in the container.xml file located in the config directory.

The agent intercepts the events posted on the event bus.

Important Note

When a new version of the software is delivered, make sure to keep the container.xml shipped with the application and add to this container.xml, the new agent entry.

Writing Code

Let's create a concrete agent: MyBrowserAgent

• Create a myBrowser package in the agents package.
• Create a class MyBrowserAgent, this class must implements the Agent interface to be initialised and the AgentListener to interact with other agents.

public class MyBrowserAgent
    implements Agent, AgentEventListener
{

    /** Reference to the registry. */
    private static Registry         registry;

    //no-arguments constructor required for initialisation
    public MyBrowserAgent() {}

    //Follow methods required by the Agent Interface

    //No-op implementation in general
    public void activate()
    {
        //this method will be invoked during the activation by the container
    }

    //invoked before shutting down the application
    public boolean canTerminate() { return true; }

    //not yet implemented: invoked when shutting down the application
    public Map<String, Set> hasDataToSave() { return null; }

    //invoked while shutting down the application
    public void terminate() {}

    public void setContext(Registry ctx)
    {
        //Must be a reference to the Agent Registry to access services.
        registry = ctx; 

        //register the events the agent listens to e.g. BrowseImage
        EventBus bus = registry.getEventBus();
        bus.register(this, BrowseImage.class);

    }



    //Follow methods required by the AgentEventListener Interface
    public void eventFired(AgentEvent e)
    {
        if (e instanceof BrowseImage) {
            //Do something
            browseImage((BrowseImage) e);
        }
    }

}

Where to Create the BrowseImage event

• Create a myBrowser package in the agents.events package
• Create a BrowseImage event in the myBrowser package

public class BrowseImage          
    extends RequestEvent
{

    /** The id of the image to browse. */
    private long imageID;
    
    /**
     * Creates a new instance.
     * 
     * @param imageID The id of image to view.
     */
    public BrowseImage(long imageID)
    {
        if (imageID < 0) 
            throw new IllegalArgumentException("ImageID not valid.");
        this.imageID = imageID;
    }
    
    
    /**
     * Returns the ID of the image to browse.
     * 
     * @return See above. 
     */
    public long getImageID() { return imageID; }

}

Listen to the BrowseImage event

To listen to events posted on the event bus, the agent must implement the AgentListener Interface and register the events to listen to.

• Register BrowseImage in the setContext(Registry) method of the Agent interface.
• Listen to BrowseImage in the eventFired(AgentEvent) method of the AgentListener interface.

Somewhere in the Data Manager for example, when clicking on an image, the following event is posted:

EventBus bus = registry.getEventBus();
bus.post(new BrowseImage(imageID));

The MyBrowserAgent handles the event

    public void eventFired(AgentEvent e)
    {
        if (e instanceof BrowseImage) {
            //Do something
            browseImage((BrowseImage) e);
        }
    }

Create An Agent's View

See Build an Agent View

Declare The Agent

What we need to do now, we need to declare MyBrowserAgent in the container.xml

• Open the container.xml located in the config folder (see Directory Contents)
• Add the following:

  <agents>
      <structuredEntry name="/agents" type="agents">
        
        <!-- NOTE FOR DEVELOPERS
             Add an agent tag for each of your Agents.
             The name tag specifies the human-readable name of the Agent.
             The active tag specified if the agent is turn on or off.
             Set to true to turn the agent on, false otherwise.
             The class tag specifies the FQN of the Agent class.
             The config tag specifies the name of the Agent's configuration file
             within the config directory.
        -->
       <agent>
          <name>My Browser</name>
          <active>true</active>
          <class>org.openmicroscopy.shoola.agents.mybrowser.MyBrowserAgent</class>
          <config>mybrowser.xml</config>
        </agent>
  ...
      </structuredEntry>
    </agents>
  
  

Note: The active tag will be added from Beta3.1

• Create a mybrowser.xml and add it to the config directory

  <?xml version="1.0" encoding="utf-8"?>
  <agent name="My Browser">
     <resources>
       <iconFactories>
  	<!-- This entry is turned into an instance of: 
         org.openmicroscopy.shoola.env.config.IconFactory
         This object can then be used to retrieve any image file within
         the directory pointed by the location tag. -->
         <structuredEntry name="/resources/icons/Factory" type = "icons">
           <!-- The location tag specifies the FQN of the package that contains
           the icon files. -->
           <location>org.openmicroscopy.shoola.agents.myBrowser.graphx</location>
         </structuredEntry>
  
       </iconFactories>
       <fonts>
         <!-- This entry is turned into an instance of java.awt.Font. --> 
         <structuredEntry name="/resources/fonts/Titles" type="font">
           <family>SansSerif</family>
           <size>12</size>
           <style>bold</style>
         </structuredEntry>
       </fonts>
  </resources>
  </agent>
  
  

  The file mybrowser.xml allows the agent to define specific parameters.

---

See Code organisation, Retrieve Data From Server