Capacity

The notion of Capacity

The notion of capacity enables the representation of agent competences. Each agent has, since its creation, a set of basic skills, including the ability to play roles (and therefore communicate), to obtain information on existing organizations and groups within the platform, create other agents, and obtain new capacities. The capacity concept is an interface between the agent and the roles it plays. The role requires some capacities to define its behaviour, which can then be invoked in one of the tasks that make up the behaviour of the role. The set of capacities required by a role are specified in the role access conditions. A capacity can be implemented in various ways, and each of these implementation is modelled by the notion of CapacityImplementation.

How to create a capacity and its first implementation

When you wants to define a capacity that will then be used to define the behavior of a role, you have at least to define one interface that correpsonds to the capacity and one class for its first implementation. The java code below describes the implementation of a very simple capacity.

// Annotations are used to specify the type of the parameters and results of the capacity
@CapacityPrototype(
		allInput=Integer.class,
		output=Double.class
)
public interface MyCapacity extends Capacity
{
// This part usually remains empty
 
}

public class MyCapacityImpl extends CapacityImplementation implements MyCapacity
{
	public MyCapacityImpl() {
		//Define the type of capacity implementation
		super(CapacityImplementationType.DIRECT_ACTOMIC);
	}
 
	@Override
	public void call(CapacityContext call) throws Exception {
		Integer p;
		Double result = 0;
		//Process inputs
		for(Object o : call.getInputValues()) {
			p = (Integer)o;
			//do something
		}
		//do something
		//Set outputs
		call.setOutputValues(result);
 
	}
}

How to add capacities to an agent

public class MyAgent extends Agent {
	public MyAgent() {
	}
 
	@Override
	public Status activate(Object... params) {
		//Capacity initialization : adding capacity
		CapacityContainer cc = getCapacityContainer();
		cc.addCapacity(new MyCapacityImpl());
		cc.addCapacity(new MyCapacity2Impl());
 
		//After and only capacity initialization, you can request the role that requires these capacities
 
		return StatusFactory.ok(this);
	}	
}

How to use capacities to define role behavior

To use a capacity in its behavior, a role have to specify it in its obtain conditions. An agent which wants to play this role must thus provide an implementation to the required capacities to access to the desired role.

How to use role API in capacity implementation

Sometimes a capacity implementation may send a message, request a role, etc. These features are available from the role which is invoking the capacity implementation.

To access to a subset of the role's functions, the capacity implementation must extend the RoleCapacityImplementation class. RoleCapacityImplementation class provides useful wrapping functions to invoke several role's functions as if the capacity caller role has invoked them.

The following example illustrates a capacity implementation, which is able to send a message to all the players of a role.

public class MyCapacityImpl
extends RoleCapacityImplementation
implements MyCapacity {
	@Override
	public void call(CapacityContext context) throws Exception {
		Message m = new StringMessage("Hello world!");
                broadcastMessage(context, ARole.class, m);
                context.success();
	}	
}

Related Pages

• Tutorials