org.iids.aos.agent
Class AgentStore

java.lang.Object
  org.iids.aos.agent.AgentStore

public class AgentStore
extends java.lang.Object

Handle for agent storage space. An agent can carry along data with it. Usually the entire object graph of an agent is serialized upon migration, which may be too expensive for large data (like audio or video content). Therefore the data can also be kept in the Agent Container of the agent, so we have no useless (un)marshalling of data everytime an agent migrates. Agents that are not written in Java require agent stores because they usually need to do manual serialization of their state. This can also be done using agent store. Creating, listing and deleting agent stores is generally done using the @see org.iids.aos.agent.AgentScape interface.

Author:

rjtimmer

Constructor Summary

AgentStore(int agentContainerID, int segmentID, KernelClient kernelClient, Cookie kernelCookie)
Create new agent store handle 'by reference'.

AgentStore(java.lang.String description, int agentContainerID, KernelClient kernelClient, Cookie kernelCookie, byte[] data)
Create new agent store.

Method Summary

void	delete() Delete the AgentStore from the AgentContainer.
java.lang.String	description() Get description (meta data) of AgentStore.
byte[]	read() Read data stored in the AgentContainer.
int	segmentID() Get AgentContainer segment id in which the AgentStore resides.
int	size() Return the size of the data in the agent store.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AgentStore

public AgentStore(java.lang.String description,
                  int agentContainerID,
                  KernelClient kernelClient,
                  Cookie kernelCookie,
                  byte[] data)
           throws KernelException

Create new agent store. Data is stored using AOS (AgentScape kernel) by the AgentScape middleware. Agents can not use this constructor directly as they have no knowledge of kernel cookies and agent containers.

This constructor creates a new segment in AOS.

Parameters:

description - Meta-data of agent store. Max 255 chars long.

agentContainerID - ID of the agent container to store the segment

kernelClient - AOS kernel client handle.

kernelCookie - Cookie to identify the role to use.

data - Data to store in the AgentStore.

Throws:

KernelException - If the store could not be created.

AgentStore

public AgentStore(int agentContainerID,
                  int segmentID,
                  KernelClient kernelClient,
                  Cookie kernelCookie)
           throws UnknownStoreIDException

Create new agent store handle 'by reference'. This constructor can be used to create an AgentStore handle for segments that are already present in the AC. When this handle is created it is checked whether the segment already exists, and if access to it is actually allowed.

Parameters:

agentContainerID - ID of the agent container to store the segment

segmentID - ID of the segment which contains the agent store

kernelClient - AOS kernel client handle.

kernelCookie - Cookie to identify the role to use.

Throws:

UnknownStoreIDException - If the segment contains no agent store or for some other reason (KernelException) the agent store cannot be accessed.

Method Detail

description

public java.lang.String description()

Get description (meta data) of AgentStore.

segmentID

public int segmentID()

Get AgentContainer segment id in which the AgentStore resides.

size

public int size()

Return the size of the data in the agent store.

read

public byte[] read()
            throws KernelException

Read data stored in the AgentContainer. This data is read from the AgentScape kernel. It is cached for some sort of efficiency.

Throws:

KernelException - If the data cannot be read from the kernel.

delete

public void delete()
            throws KernelException

Delete the AgentStore from the AgentContainer. Data is removed from the AgentContainer, any further attempts to use this handle for reading will fail.

Throws:

KernelException - If the AgentStore could not be deleted.