Netbeans Plugin
From Agent Factory
Editorial History
05/04/2008: Version 1 - Introduction & Installation Guide
08/04/2008: Version 2 - Added "Using the Nebeans Plugin" section introduction & How to create a project
07/11/2008: Version 3 - Updated to reflect rewritten Netbeans Plugin.
08/12/2008: Version 4 - Getting Help, Deploying an Application & Updating Agent Factory sections have now been written + various small edits.
Introduction
Agent Factory can be installed as a plugin within the Netbeans IDE. Currently, the plugin provides support for:
- Deploying (executing) agents systems based on multiple configurations.
- Writing and compiling of AFAPL2 code.
- Templates for Platform Configuration Files (CFG), Community Initialization Scripts (APS), Actuators, Perceptors, Modules, and Platform Services.
- Debugging of agent systems (via the Agent Factory Debugger which is a plugin to the Run-Time Environment rather than Netbeans)
- Creation of Agent Factory projects
To develop agent-based applications using Agent Factory, you can either make use of one of the pre-existing agent architectures / languages, or develop one of your own. Details of how to develop AFAPL2 agents can be found in the AFAPL2 Programmers Guide, while information on the Reactive Message Agent can be found here. Alternatively, to develop your own agent architecture / language, please read the Architecture / Interpreter Development Guide.
Additionally, a key feature of the Run-Time Environment is the support for shared resources in the form of Platform Services. To learn how to develop a Platform Service, please see the Platform Service Development Guide.
If you wish to get a better idea about where Agent Factory has been used, or look at some example applications that have been developed using Agent Factory, please see the Projects page.
Downloading the Module & Getting Help
The Netbeans Modules can be downloaded from either Sourceforge or from the Netbeans Plugin Portal. Alternatively, you can download the source code from the Agent Factory SVN repository on Sourceforge.
This plugin has been created to support developers wishing to use Agent Factory. Should you have any questions / issues, the best place to get answers and help is through the Source Forge Help Forum.
Installing the Plugin
Unzip the plugin files and start the Netbeans IDE. When started, goto the Tools menu and select the Plugins option. When the Plugins dialog opens, selected the "Downloaded" tab. You should have a screen that looks something like this:
Next, click on the "Add Plugins..." button, goto the folder into which you extracted the Agent Factory plugins, and select the plugin file as is shown below:
When added, you should be returned to the main Plugins dialog, and the Agent Factory plugin (called AF-IDE) should now appear in the downloaded list as is shown below:
Finally, click on the "Install" button in the bottom left corner of the Plugins Dialog. Answer all questions normally for the installation of the plugins. At the end of the process, you will be asked to restart the Netbeans IDE, and after that you are ready to go!
Running the Examples
One of the quickest and easiest ways of starting to understand what Agent Factory is, and how it works, is to look at the simple example applications that come with the plugin. Each of these examples is implemented as a Netbeans Project Template and can be created via the project wizard.
The screen shot above is taken from version 2.0.7 of the plugin, which contained three example applications.
The Alive Application
To load the Example Alive Application, select the corresponding project template in the "Agent Factory" category of the New Project wizard, and select a name (here, we will use the name "AliveExample"). This project contains a very simple AFAPL2 agent that generates a Belief that it is alive via use of a simple Perceptor unit. The figure below shows the structure of the project when it has been created:
As can be seen in the above image, the application includes a single AFAPL2 agent that has been written in a file entitled "Alive.afapl2". The AFAPL2 program consists of two parts:
- The "alive" Ontology: this specifies valid statements that can be made about the state (beliefs) of the environment. In this case, the ontology specifies one predicate, state, that takes one argument, namely the state of the agent.
- The "alive" Perceptor: this is a part of an AFAPL2 agent that can be used to generate partial environment states (beliefs). In this case, the Perceptor will be used to generate a belief about the state of the agent (i.e. that it is alive).
While the Perceptor unit is specified in the AFAPL2 file, it is implemented as a Java class, whose source code is given below:
package perceptor;
import com.agentfactory.logic.agent.Perceptor;
public class Alive extends Perceptor {
public void perceive() {
adoptBelief("BELIEF(state(alive))");
}
}
As can be seen in the above figure, the CLASS parameter in the Perceptor definition is used to associate a specific Java class with the perceptor definition.
To run this example, simply press Shift-F3 or right-click over the project node and select "Run Platform". This will start up an instance of the Agent Platform that has been configured to use the Agent Factory Debugger. A screenshot of this debugger is shown below:
To see what the example does (which is not much), double click on the agent called "Rem" which is displayed in the list on the left-hand side of the debugger, and maximise the debugger window. Finally, select the "Belief" tab and click on the "Step" button. You should get something that looks like the screenshot below:
Overall, the point of this example is to illustrate how the Perceptor component of an AFAPL2 agent works. As can be seen, the Perceptor is responsible for generating beliefs about the state of the environment. Each Perceptor associated with the agent is triggered at the start of each iteration of the agents execution cycle, and the resultant beliefs generated are added to the agents belief set.
The Agent Creation Application
To load the Agent Creation Application, select the corresponding template from the list provided in "Agent Factory" category of the Netbeans Project Wizard, and choose a name (here we will use the name "AgentCreation"). This project contains another AFAPL2 agent that is given an initial belief, and which performs one basic task, namely to dynamically (at run-time) create and initialise another agent of the same type. The figure below show the structure of the project, once created:
Creating a New Project
The plugin can be used to develop all types of Agent Factory component, from run-time tools and new agent architectures to platform services and agents that are programmed using a pre-existing agent interpreter / architecture. However, the core support provided in the current version of the plugin is oriented towards the deployment of agents systems and the programming of agents using the AFAPL2 Development Kit. The following sections, outline how to create an Agent Factory project, write a simple AFAPL2 agent program (taken from the AFAPL2 Programmers Guide), and deploy an agent system containing an agent that is based on that agent program.
Creating the Project
To create a project, go to File->New Project. If the Netbeans Plugin has been installed correctly, then there should be an "Agent Factory" category of project and if you select it, you should be able to create a new "Basic Agent Factory Project". The screenshot below shows the project selection dialog with the "Agent Factory" category selected.
To create an Agent Factory application, click on the "Next" button. This leads you to a project customization page in the Project Creation Wizard, a screenshot of which can be seen below.
Once you click on the finish button, an Agent Factory project is created. As can be seen in the screenshot below, this project contains a sample default Agent Platform Script file, and a sample default Platform Configuration File. In addition, a number of Agent Factory specific libraries have also been installed in the project. These libraries reflect the latest major snapshop of the Agent Factory System.
You are now ready to start writing Agent Factory applications and components...
Agent Factory Templates
You create an Agent Factory application by developing various components and writing the corresponding agent code to specify how those components should be used. To create any of these bits, you will need to make use of templates that are provided in the "Agent Factory" category of the Netbeans New File Wizard:
The sections below will explain briefly what each of these templates is and how to use them.
Agent Platform Templates
These templates are provided to support the creation of Agent Platform level components that can are common to all of the development kits that are associated with Agent Factory.
The Main Class Template
The Main class template is an outline of a Java class that should be used to deploy Agent Factory applications. Details of the typical structure of the main method can be found in the Java-based Deployment Guide. The default template provided is given below:
import com.agentfactory.afapl2.interpreter.AFAPL2ArchitectureFactory;
import com.agentfactory.platform.core.DuplicateAgentNameException;
import com.agentfactory.platform.core.IAgent;
import com.agentfactory.platform.core.NoSuchArchitectureException;
import com.agentfactory.platform.impl.DefaultAgentPlatform;
import com.agentfactory.platform.impl.RoundRobinTimeSliceFixedScheduler;
import com.agentfactory.service.ams.AgentManagementService;
import com.agentfactory.visualiser.Debugger;
import java.util.HashMap;
import java.util.Properties;
import java.util.logging.Level;
import java.util.logging.Logger;
/**
* Example Main class that illustrates how to deploy a basic Agent Factory
* application.
*
* @author rem
*/
public class Main {
public static void main(String[] args) {
// Create a new agent platform with a basic name and domain
DefaultAgentPlatform platform = new DefaultAgentPlatform();
platform.setName("test");
platform.setDomain("ucd.ie");
// Install a scheduling algorithm for executing the agents
platform.setScheduler(new RoundRobinTimeSliceFixedScheduler());
// Install and register the AFAPL2 Architecture Factory:
// This enables support for instantiating AFAPL2 agents (i.e. agents
// whose source code is identified by a .agent extension)
AFAPL2ArchitectureFactory factory = new AFAPL2ArchitectureFactory();
Properties props = new Properties();
props.setProperty("TIMESLICE", "100");
factory.configure(props);
platform.getArchitectureService().registerArchitectureFactory(factory);
// Install and start the Agent Factory Debugger
Debugger debugger = new Debugger();
debugger.init(new HashMap<String, String>(), platform);
debugger.start();
// Get a reference to the Agent Management Service so that the default
// agent community can be created...
AgentManagementService ams = (AgentManagementService) platform.getPlatformServiceManager().getServiceByName(AgentManagementService.NAME);
try {
// 1. Create an agent
IAgent agent = ams.createAgent("rem", "com/agentfactory/afapl2/core/agent/AMSSupport.agent");
// 2. Give it initial beliefs / goals
agent.initialise("BELIEF(happy)");
// 3. Resume the agent (start it)
ams.resumeAgent("rem");
} catch (NoSuchArchitectureException ex) {
Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
} catch (DuplicateAgentNameException ex) {
Logger.getLogger(Main.class.getName()).log(Level.SEVERE, null, ex);
}
}
}
The New Agent Architecture Template
Agent Factory is a generic framework for creating and deploying multi-agent systems. As such, it has been designed to support heterogeneous agent implementation. This template allows developers to create new kinds of agent architecture, or even build custom Java agents are not based on any pre-existing architecture. To read more about how to create a new agent architecture, please see the Architecture / Interpreter Development Guide.
The New Platform Service Template
A Platform Service is a shared platform-level resource for agents. Although the most common type of platform service is a Message Transport Service, Platform Services should be used to model any type of resource that can be accessed by more than one agent. Examples of other kinds of platform service include the Agent Management Service, shared whiteboard services, file transfer services (e.g. EFRAFA), and framework access points (e.g. for component-style frameworks such as CARTAGO and SoSAA).
For more details on how to build a Platform Service, see the Platform Service Development Guide.
The New Message Transport Service Template
Message Transport Services are a special type of Platform Service. To facilitate their development, we have created an abstract base class that extends the core Platform Service implementation. To learn more about how to create a Message Transport Service, please see the Platform Service Development Guide.
AFAPL2 Templates
These templates are specific to the AFAPL2 Development Kit which is provided as part of the plugin. To learn more about how to create an AFAPL2 agent, please read the AFAPL2 Programmers Guide. Currently, templates are provided for the following:
- AFAPL2 code
- Actuators
- Perceptors
- Modules
Each of these templates are outlined in detail below.
The New AFAPL2 File Template
This template should be used to write a AFAPL2 agent programs. To create an AFAPL2 file, select "New AFAPL2 File" and click the "Next" button. The wizard will then prompt you to provide the name of the AFAPL2 program that you want to write (the ".afapl2" extension is appended automatically), and clicking the "Finish" button will cause the file to be created. Typically, this file will take a form similar to the one shown below:
This file includes a sample ontology and a sample initial belief for the agent. You can replace this with the relevant agent code, and can compile this code by pressing F10 or by right-clicking on the relevant node in the project view and selecting the "Compile" option (it is also automatically included in any package / project build). For more details on how to write an AFAPL2 agent, please read the AFAPL2 Programmers Guide.
The AFAPL2 Actuator Template
Actuator units are one of the core Java components that underpin AFAPL2 programs. They are used to implement the primitive actions that can be performed by an AFAPL2 agent. To create an actuator, choose the "AFAPL2 Actuator" template and click on the "Next" button. When prompted, give the name of the actuator, and press the "Finish" button. This will create a Java class similar to the one presented below:
The resultant Java code is an outline for the implementation of the Actuator. As can be seen above, this class extends the core com.agentfactory.logic.agent.Actuator class and creates a black act(...) method. You should write your actuator code in this class. This code is then linked to an AFAPL2 agent via the ACTION construct. For example, the actuator in the figure would be associated with an action of the form:
ACTION example {
PRECONDITION BELIEF(true);
POSTCONDITION BELIEF(true);
CLASS actuator.MYActuator;
}
For more details on how to create an actuator, please read the AFAPL2 Programmers Guide.
The AFAPL2 Perceptor Template
Perceptor units are one of the core Java components that underpin AFAPL2 programs. They are used to implement the basic sensing capabilities of an AFAPL2 agent. To create a perceptor, choose the "AFAPL2 Perceptor" template and click on the "Next" button. When prompted, give the name of the perceptor, and press the "Finish" button. This will create a Java class similar to the one presented below:
The resultant Java code is an outline for the implementation of the Perceptor. As can be seen above, this class extends the core com.agentfactory.logic.agent.Perceptor class and creates a black perceive() method. You should write your perceptor code in this class. This code is then linked to an AFAPL2 agent via the PERCEPTOR construct. For example, the perceptor in the figure would be associated with an agent via code of the form:
PERCEPTOR example {
CLASS perceptor.NewPerceptor
}
For more details on how to create a perceptor, please read the AFAPL2 Programmers Guide.
The AFAPL2 Module Template
Modules are internal resources that may be used by an agent to implement additional data structures that more appropriately model the environment, or to instantiate interfaces to external applications. Modules are Java classes that extend the com.agentfactory.logic.agent.Module class and, where necessary, override the init() method. Modules can be accessed via Actuator and/or Perceptor units, which provide three helper methods that support retrieval of Module instances.
To create a Module, choose the "AFAPL2 Module" template and click on the "Next" button. When prompted, give the name of the perceptor, and press the "Finish" button. This will create a Java class similar to the one presented below:
package module;
import com.agentfactory.logic.agent.Module;
public class Queue extends Module {
public void init() {
// INSERT INITIALISATION CODE HERE!
}
}
By way of example, lets look at the code for a simple Queue Module:
package module;
import com.agentfactory.logic.agent.Module;
import java.util.LinkedList;
public class Queue extends Module {
private LinkedList list;
public void init() {
list = new LinkedList();
}
public void enqueue(Object item) {
list.insertFirst(item);
}
public Object top() {
return list.getLast();
}
public Object dequeue() {
return list.removeLast();
}
public int size() {
return list.size();
}
public boolean isEmpty() {
return list.isEmpty();
}
}
Modules are associated with AFAPL2 agents via the LOAD_MODULE construct. An AFAPL2 agent can have many instances of the same Module. Each Module instance is identified by a unique name that is specified in the AFAPL2 program. For example, the following code specifies an incoming jobs queue that is part of a Service Provided agent:
LOAD_MODULE incomingJobs module.Queue;
To use a module, you must write an associated set of Actuator and Perceptor units, which retrieve a reference to the module instance and extract or update the module state as is appropriate. For example, the code below would be part of a Perceptor unit that is designed to extract information about the current state of the incoming jobs queue:
package perceptor;
import module.Queue;
import com.agentfactory.logic.agent.Perceptor;
public class QueueState extends Perceptor {
public void perceive() {
Queue queue = (Queue) getModuleByName("incomingJobs");
adoptBelief("BELIEF(size(" + queue.size() + "))");
adoptBelief("BELIEF(top(" + queue.top() + "))");
}
}
Similar code can be used in an Actuator unit to perform updates on the Module, such as, inserting an item into the queue.
RMA Templates
These templates provide support for the creation of Reactive Message Agent agents, a pure-Java based agent architecture that supports the creation of agents that respond to environment events and/or messages. For further details on how to create this class of agents, please read the RMA Programmers Guide. When building agent-based applications using this architecture, you may also need to make use of the templates listed in the Agent Platform Templates section above.
The New Reactive Message Agent Template
This template supports the creation of new agents based on the Reactive Message Agent architecture, which is a 100% Java based. To create a new RMA Agent, you simply create a new Java class based on this template, and then customise it as necessary. The outline code provided by this template takes the form:
public class Tester extends ReactiveMessageAgent {
public Tester(String name, AgentPlatform platform) {
super(name, platform);
// INITIALIZE MEMORY:
memory.put("lookups", new HashMap());
// BIND TO REQUIRED SERVICES
bindToService(AgentManagementService.NAME);
// ADD MESSAGE AND EVENT HANDLERS
// e.g. addMessageHandler(new CreateHandler(this, Message.REQUEST));
// e.g. addEventHandler(new RegistrationEventHandler(this));
}
/**
* DO POST CREATION INITIALIZATION STUFF HERE (DELETE IF NOT NEEDED)
*/
public void metaRegistration() {
super.metaRegistration();
initializeRegister();
}
}
For more details on how to create this style of agent, please see the Reactive Message Agent and RMA Programmers Guide pages.
The New RMA Message Handler Template
Message Handlers are used to handle incoming messages that are received by the agent. The template code for a message handler looks like this:
public class NewMessageHandler extends MessageHandler {
public NewMessageHandler(ReactiveMessageAgent agent, String performative) {
super(agent, performative);
}
/**
* This method checks whether the Handler should be used to handle the
* specified incoming message.
*
* @param message the message being handled
* @returns true if the handler should handle the message, or false otherwise
*/
public boolean filter(Message message) {
// Example filter: checks that the language is AFAPL and the content starts
// with "happy"
if (!message.getLanguage().equals("AFAPL")) {
return false;
}
return message.getContent().startsWith("happy");
}
/**
* This method actually handles the message.
*
* @param message the message being handled
* @returns true if everything is good (i.e. no errors), or false otherwise
*/
public boolean act(Message message) {
// Sample message:
AgentID receiver = (AgentID) map.get(replyWith);
StringMessage response = StringMessage.newInstance();
response.setPerformative(Message.INFORM);
response.setLanguage("AFAPL");
response.setSender(agent.getAgentID());
response.getReceivers().add(receiver);
response.setContent(message.getContent());
response.setContentLength(response.getContent().length());
return send(response);
}
}
As can be seen, the filter(...) method is used to perform a simple check that determines whether this handler can be used to handle the incoming message. Iif it can, then the act(...) method defines what will be done. Note that if the return value of this method is false, then the agent continues looking for a Message Handler that can handle the message (failure is treated as meaning that this wasn't the correct Message Handler after all.
The New RMA Event Handler Template
Event Handlers are used to handle internal events generated by either the agent, or any external systems that the agent is linked to. They have a similar structure to Message Handlers as they also employ two methods. The filter(...) method checks whether the handler is appropriate for the event, and the act(...) method does something in response to the event. Again, a false return value from act(...) method is read as implying that the event handler was not necessarily the correct one for the current event.
Deploying an Application
As of Version 2.0, the procedure for deploying an Agent Factory application has changed and is now based on the use of a Main class. Prior to this version, deployment was performed based on the creation of two configuration files. Each of these approaches are outlined in the subsections below.
Configuration-based Deployments
To deploy an application, you first need to select which Platform Configuration File and Agent Platform Script you will use. There are currently two ways of doing this, which are outlined in the sections below. Once you have done this, an application can be deployed by simply right-clicking over the project node in the Netbeans Project View and selecting "Run Platform". This will start up an Agent Factory Run-Time Environment that is configured based on the selected configuration files. Alternatively, if the project is set as the currently active project, then you can simple pres "Shift-F3".
Selecting the Defaults via the Context Menu
One way of selecting which configuration files you will use is to identify the relevant files, and you should right-click over each file node in the Netbeans Project View, and select "Set as Default Platform Script" or "Set as Default Configuration Files" as appropriate.
Selecting the Defaults via the Project Properties form
The second way of selective the configuration files is via the project properties editor, which is shown below.
As can be seen, the editor includes a "Deploy Agent Platform" setting in which you can see the current default Platform Configuration File and Agent Platform Script. To change these defaults, simply edit the relevant text box and press return (a later release will support a browsing behaviour via the "Browse" buttons).
Java-based Deployments
To deploy an application via Java, you simply need to write a Main class (i.e. a main() method) that creates and configures the agent platform and deploys an initial population of agents on that platform. Further details can be found in the Java-based Deployment Guide.
Updating the Library
As was indicated earlier, it is possible to update projects so that they use a newer version of Agent Factory. To do this, you must replace the default jar files that are associated with an Agent Factory project with the new release. To do this, you should open the Netbeans Library Manager (Tools->Libraries). Locate and select "AF-Library" in the Libraries list.
Now, do one of the following:
- Remove the existing Jar files and add the new Jar files
- Identify the folder in which the current Jar files are located and copy the new Jar files over them.
Either approach is fine, and will result in ALL Agent Factory projects moving to the new version of Agent Factory. If you wish to update only one of the projects, then you should remove the Library jars via the "Libraries" node of the project in the Netbeans Project View, and add the new Jars to only that project.
