Agent System POND 1.2 (28.2.2002)

PkgAgentSystem
Class AgentSystem

java.lang.Object
  |
  +--java.lang.Thread
        |
        +--FIM.Util.Threads.CancellableThread
              |
              +--PkgAgentSystem.AgentSystem
All Implemented Interfaces:
Runnable
Direct Known Subclasses:
GUIAgentSystem

public class AgentSystem
extends CancellableThread

Main class of the agent system.

Version:
1.0, 1.7.2000
Author:
Michael Sonntag

Field Summary
static boolean DEBUG
          Flag for debugging.
static boolean HAND_OFF
          Flag for whether Hand-Off should take place or not
static int MAX_DEFER_DELAY
          Maximum allowed for delaying persisting or moving through request of the agent
static int MIN_DEFER_DELAY
          Minimum allowed for delaying persisting or moving through request of the agent
protected static Currency priceCurrency
          The currency used for prices when selling permissions.
static boolean SECURE_CONNECTION
          If true, the connection to another agent-system will be cryptographically secure.
protected  PersonalSecurityStore securityStore
          The security store of the owner of this agent system
(package private)  Vector servingThreads
          List of all serving threads currently active.
(package private) static int STD_PORT
          The standard port of the agent system.
 
Fields inherited from class java.lang.Thread
inheritableThreadLocals, MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY, threadLocals
 
Constructor Summary
  AgentSystem(int port, String libraryDir, String agentDir, String systemDir, boolean exitOnLast, String savedFile)
          Creates a new agent system with the security turned on.
protected AgentSystem(int port, String libraryDir, String agentDir, String systemDir, boolean exitOnLast, String savedFile, boolean useSecurity)
          Creates a new agent system.
  AgentSystem(String libraryDir, String systemDir)
          Creates a new agent system with the default value for the port and the users home directory as directory from where the agents are loaded.
 
Method Summary
protected  boolean acceptPayment(AgentData agData, Payment payment)
          Check whether we want to accept this payment for a permission from a certain agent.
protected  int agentCount()
          Returns the number of agents in this system.
protected  boolean allowArrivalOfAgent(URL whereFrom, AgentIdentity identity, CertificateWrapper[] codeSigners, String agentClass)
          Checks whether this agent is allowed to arrive at this host.
 Permission buyPermission(AgentBase agent, Permission perm, Payment payment)
          Allows the agent to buy a permission.
 PermissionCollection buyPermissionSet(AgentBase agent, PermissionCollection perms, Payment payment)
          Allows the agent to buy a set of permissions.
 void cancel()
          Method to stop the agent system gracefully.
protected  void challengeAgent(AgentData data)
          Challenges the agent for the knowledge of its private key.
protected  boolean checkAdditionalClassification(AgentData agData, AgentClassification classification)
          Checks whether an additional classification is accepted.
protected  void dePersist(AgentData data)
          Restores a persisted agent to the running state.
 void deploy(AgentData agData)
          Deploys the agent by signing the current state (i. e. the initialization parameters) and the code used if applicable (digest over the code signatures)
protected  void destroyPersistedAgent(AgentData data)
          Terminates a currently persisted agent.
(package private)  void doTimerAction(long id)
          Handles delayed requests.
 void dumpClassification(AgentBase agent)
          Prints the classification information to System.out.
protected  AgentData getAgentContext(AgentBase agent)
          Get the management data of an agent from a supplied reference to it.
protected  AgentData getAgentContext(AgentIdentity identity)
          Get the management data of an agent from its identity.
protected  String getAgentDirectory()
          Returns the directory from where the agents are loaded.
 AgentIdentity getAgentIdentityByID(String ID)
          Retrieve the identity of a local agent by its unique ID.
 ClassificationSet getClassificationStatus(AgentBase agent)
          Allows an agent to get information on his current status of additional classifications.
 Certificate[] getCodeCertificates(AgentBase agent)
          Allows an agent to get information on his accepted code certificates.
protected  String getLibraryDirectory()
          Returns the directory where the shared libraries are located.
 URL getLocation()
          Returns the URL of the local agent system.
 PermissionCollection getOptionalPermissions(AgentBase agent)
          Returns a collection of all optional permissions.
 Invoice getPrice(AgentBase agent, Permission perm)
          Return the price of a permission for an agent.
 URL getResource(AgentBase agent, String name)
          Finds the resource with the given name.
 InputStream getResourceAsStream(AgentBase agent, String name)
          Finds the resource with the given name and returns an input stream for reading it.
 Enumeration getResources(AgentBase agent, String name)
          Finds all the resources with the given name.
 Invoice getSetPrice(AgentBase agent, PermissionCollection perms)
          Return the price of a set of permissions for an agent.
protected  String getSystemDirectory()
          Returns the directory where the agentsystem files are located.
protected  boolean isPrivilegedSource(CodeSource codesource)
          Check whether a code is form a privileged package or not.
(package private)  void localBroadcastMessage(AgentBase sender, BroadcastMessage msg)
          Sends a message to all agents in the local system, except the sender and the persisted ones.
static void main(String[] args)
          This class can also be used directly to show a GUI-less agent system:
java PkgAgentSystem.AgentSystem agentDir libraryDir [Port [savedFile]]
protected  void move(AgentBase agent, URL destination)
          Transfers an agent to another host.
 ClassificationSet offerAdditionalClassification(AgentBase agent, ClassificationSet offer)
          Allows an agent to offer additional classifications to receive more/cheaper permissions.
protected  void onAgentCreated(AgentData data)
          Placeholder for updating the user interface after an agent was created.
protected  void onAgentDepersisted(AgentData data)
          Placeholder for updating the user interface after an agent was depersisted.
protected  void onAgentDestroyed(AgentData data)
          Placeholder for updating the user interface after an agent was destroyed.
protected  void onAgentPersisted(AgentData data)
          Placeholder for updating the user interface after an agent was persisted.
protected  void onAgentReceived(AgentData data)
          Placeholder for updating the user interface after an agent was received.
protected  String open(String filename, String password)
          Reades the agent system with all contained agents from a file.
protected  void persist(AgentBase agent)
          Persists an agent to the disk.
(package private)  void receiveAgent(AgentData data)
          Starts a received agent.
protected  void reportError(String msg)
          Report an error to the user.
 void returnPermission(AgentBase agent, Permission perm)
          An agent can return a permission, indicating that he no longer needs it.
 void returnPermissionSet(AgentBase agent, PermissionCollection perms)
          An agent can return permissions, indicating that he no longer needs them.
 void run()
          Main method of the system: Wait for incoming requests and handle them.
protected  String save(String password)
          Saves the agent system with all contained agents to the default file.
protected  String saveAs(String filename, String password)
          Saves the agent system with all contained agents to a file.
protected  void saveHandOff(boolean sender, Certificate otherASIdentity, AgentIdentity agentIdentity, byte[] digest, byte[] outSig, byte[] inSig)
          Store the hand-off we received (and sent) in a file.
(package private)  void sendMessage(AgentBase sender, Message msg)
          Sends a message to another agent.
 AgentBase startAgent(AgentBase requester, String className, boolean fromMyCodePackage, AgentIdentity identity, PrivateKey privateKey, Serializable param)
          For starting an agent by another agent.
protected  AgentBase startAgent(String className, String codeOrigin, boolean forceLocalCode, AgentIdentity identity, PrivateKey privateKey, Object param, boolean start)
          For starting an agent by the system: there is no requester.
protected  void stopAgent(AgentBase agent, boolean destroy)
          Terminates a running agent.
 boolean storeInReadOnlyStore(AgentBase requester, AgentIdentity destination, Serializable key, Serializable value)
          Tries to store an object under a certain key in the ReadOnlyStore of another agent.
protected  void storePayment(AgentData agData, Payment payment)
          Store the payment we received for granting a permission in a file.
 boolean terminate(long maxWaitToDie)
          Method to stop the agent system.
protected  Serializable transferObject(Serializable obj, ClassLoader cll)
          Transfers an object from one classloader to another.
 
Methods inherited from class FIM.Util.Threads.CancellableThread
isCancelled
 
Methods inherited from class java.lang.Thread
, activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getContextClassLoader, getName, getPriority, getThreadGroup, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setName, setPriority, sleep, sleep, start, stop, stop, suspend, toString, yield
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEBUG

public static final boolean DEBUG
Flag for debugging. If true, some error messages will be printed that are otherwise swallowed

HAND_OFF

public static final boolean HAND_OFF
Flag for whether Hand-Off should take place or not

SECURE_CONNECTION

public static final boolean SECURE_CONNECTION
If true, the connection to another agent-system will be cryptographically secure. The system can connect only to systems where this flag is the same (whether it is true or false)

MIN_DEFER_DELAY

public static final int MIN_DEFER_DELAY
Minimum allowed for delaying persisting or moving through request of the agent

MAX_DEFER_DELAY

public static final int MAX_DEFER_DELAY
Maximum allowed for delaying persisting or moving through request of the agent

STD_PORT

static final int STD_PORT
The standard port of the agent system. Package access for AMPURLConnection

servingThreads

Vector servingThreads
List of all serving threads currently active. Neede for terminating them when the system is terminated. Package access, so the threads can remove themselfes.

securityStore

protected PersonalSecurityStore securityStore
The security store of the owner of this agent system

priceCurrency

protected static final Currency priceCurrency
The currency used for prices when selling permissions.
Constructor Detail

AgentSystem

public AgentSystem(String libraryDir,
                   String systemDir)
Creates a new agent system with the default value for the port and the users home directory as directory from where the agents are loaded. The system will not terminate after the last agent is destroyed and no state will be loaded from a saved file. The security is turned on.
Parameters:
libraryDir - the directory where the common libraries are stored. Must be provided.
sytemDir - the directory, where the system is located; the keystores are located there as well as logfiles and payment-files, etc.

AgentSystem

public AgentSystem(int port,
                   String libraryDir,
                   String agentDir,
                   String systemDir,
                   boolean exitOnLast,
                   String savedFile)
Creates a new agent system with the security turned on.
Parameters:
port - the port the system will listen on (must be >1024 or -1)
libraryDir - the directory, where the common libraries are from; All agents will load classes first from there and only after not finding them there from their local path/package. Must be provided.
agentDir - the directory, where the AGENTS are from, NOT where the JDK or the agent system is located
sytemDir - the directory, where the system is located; the keystores are located there as well as logfiles and payment-files, etc.
exitOnLast - if true the system will terminate after the last agent is destroyed (may start empty however)
savedFile - if not null, the agentsystem will load the state from this file

AgentSystem

protected AgentSystem(int port,
                      String libraryDir,
                      String agentDir,
                      String systemDir,
                      boolean exitOnLast,
                      String savedFile,
                      boolean useSecurity)
Creates a new agent system.
Parameters:
port - the port the system will listen on (must be >1024 or -1)
libraryDir - the directory, where the common libraries are from; All agents will load classes first from there and only after not finding them there from their local path/package. Must be provided.
agentDir - the directory, where the AGENTS are from, NOT where the JDK or the agent system is located
sytemDir - the directory, where the system is located; the keystores are located there as well as logfiles and payment-files, etc.
exitOnLast - if true the system will terminate after the last agent is destroyed (may start empty however)
savedFile - if not null, the agentsystem will load the state from this file
useSecurity - false if no security system is wanted
Method Detail

run

public void run()
Main method of the system: Wait for incoming requests and handle them. Currently only requests for receiving an agent are allowed.
Overrides:
run in class CancellableThread
See Also:
ServingThread

cancel

public void cancel()
Method to stop the agent system gracefully. Closes the server socket. Will also cancel all the serving threads.
Overrides:
cancel in class CancellableThread

terminate

public boolean terminate(long maxWaitToDie)
Method to stop the agent system. Will try cancelling first. Closes the server socket and cancels all the serving threads. Cannot completely stop the threads, as stop is deprecated; sets their priority to a minimum then.
Overrides:
terminate in class CancellableThread
Parameters:
maxWaitToDie - number of secods to wait befor forceful termination (0 = wait indefinitely)
See Also:
Thread

getLocation

public URL getLocation()
Returns the URL of the local agent system. Can be used to move agents to this one.
Returns:
the location of this agent system

getAgentDirectory

protected String getAgentDirectory()
Returns the directory from where the agents are loaded.
Returns:
the directory from where the agents are loaded

getSystemDirectory

protected String getSystemDirectory()
Returns the directory where the agentsystem files are located.
Returns:
the directory where the agentsystem files are located

getLibraryDirectory

protected String getLibraryDirectory()
Returns the directory where the shared libraries are located.
Returns:
the directory where the shared libraries are stored

agentCount

protected int agentCount()
Returns the number of agents in this system. Both active and persisted agents are counted.
Returns:
the number of agents in this system

doTimerAction

void doTimerAction(long id)
Handles delayed requests. Only package access, so no agent can call it with some bogus id!
Parameters:
id - the id of the action to take

stopAgent

protected void stopAgent(AgentBase agent,
                         boolean destroy)
Terminates a running agent. The agent will remain visible if he should not be destroyed. In this case only its thread is terminated.
Parameters:
agent - the agent to stop
destroy - if the agent should be completely destroyed (false when persisting)

destroyPersistedAgent

protected void destroyPersistedAgent(AgentData data)
Terminates a currently persisted agent. It will no be depersisted and then destroyed, but immediately removed from the system.
Parameters:
data - the management data of the agent to destroy

persist

protected void persist(AgentBase agent)
                throws NotSerializableException
Persists an agent to the disk. Its running thread is stopped and the GUI removed. Only a small box with the name remains.
The agent can avoid being persisted by throwing a PersistingDeniedException. In this implementation this works only once. If after the allotted time the agent denies being persisted agein, it is terminated.
Parameters:
agent - the agent to persist
Throws:
NotSerializableException - if the agent cannot be serialized
See Also:
AgentBase, PersistingDeniedException

dePersist

protected void dePersist(AgentData data)
                  throws CreateAgentFailureException
Restores a persisted agent to the running state. The state information is loaded from the disk and a new thread is started.
Parameters:
data - the management data of the agent to depersist
Throws:
CreateAgentFailureException - if an error occured when starting the agent (class not found or stream error during reading)
See Also:
AgentBase

startAgent

public AgentBase startAgent(AgentBase requester,
                            String className,
                            boolean fromMyCodePackage,
                            AgentIdentity identity,
                            PrivateKey privateKey,
                            Serializable param)
                     throws CreateAgentFailureException,
                            InitializationException
For starting an agent by another agent. It will always be started immediately. You can create any agents you want for yourself, but doing agent-things (moving, persisting, receiving/sending messages) is only possible if the agent is started through the agent system.
Parameters:
requester - the agent who wants to create another agent
className - name of the class of the agent to start (including all packages)
fromMyCodePackage - if true, the code will be loaded from the package of the requesting agent. Otherwise it will be searched for normally
identity - the identity of the new agent
privateKey - the private key of the agent (might be null if identity has no public key or just not provided)
param - the parameter passed to the method initialize, which is called after starting the agent
Throws:
CreateAgentFailureException - if any exception or error happens while creating thre agent (e. g. when (de-)serializing the initialization parameter)
InitializationException - if an error occured during initialization

startAgent

protected AgentBase startAgent(String className,
                               String codeOrigin,
                               boolean forceLocalCode,
                               AgentIdentity identity,
                               PrivateKey privateKey,
                               Object param,
                               boolean start)
                        throws CreateAgentFailureException,
                               InitializationException
For starting an agent by the system: there is no requester. Here we need not serialize&deserialize the parameters: They are supplied by the system itself and can therefore be used by every agent. The user can decide whether to start the agent now or do this by itself later. You can create any agents you want for yourself, but doing agent-things (moving, persisting, receiving/sending messages) is only possible if the agent is started through the agent system.
Protected so agents can only use the method above.
Parameters:
className - name of the class of the agent to start (including all packages)
codeOrigin - file or directory where from where the code should be loaded. If null, searches for it in the agent-directory.
forceLocalCode - if true, the code will be marked as from the local host, even if it is not
identity - the identity of the agent
privateKey - the private key of the agent (might be null if identity has no public key or just not provided)
param - the parameter passed to the method initialize, which is called after starting the agent
start - true if the agent should be started (if false, it can be started later with ".start()" )
Throws:
CreateAgentFailureException - if any exception or error happens while creating thre agent
InitializationException - if an error occured during initialization

move

protected void move(AgentBase agent,
                    URL destination)
             throws ReceiveAgentDeniedException,
                    CannotSendException
Transfers an agent to another host. May fail if on the other host no agent system is installed, no connection is possible or the other host denies the agent access.
If called from the agent the execution will not return from this method as the agent is terminated in here.
Please note, that trying to send the agent will terminate all ongoing conversations and remove all pending messages, regardless of success.
Parameters:
agent - the agent to move
destination - URL of the system the agent shall be moved to
Throws:
ReceiveAgentDeniedException - if the other host denies to receive the agent (problem on remote host)
CannotSendException - if an error occured during sending (problem on this host)

receiveAgent

void receiveAgent(AgentData data)
            throws ReceiveAgentDeniedException
Starts a received agent. Package access so only ServingThread has access.
Parameters:
data - management data of the agent to receive
Throws:
ReceiveAgentDeniedException - if this systems denies this agent access (happens here only if an error occured during starting it)

getResource

public URL getResource(AgentBase agent,
                       String name)
Finds the resource with the given name. A resource is some data (images, audio, text, etc) that can be accessed by class code in a way that is independent of the location of the code. The name of a resource is a "/"-separated path name that identifies the resource.
It is searched for in the same way as the classes of this agent (classpath, library dir and package/agent dir)
To support things no longer possible, as access to any classloader is denied.
Parameters:
agent - the agent who wants a resource
name - name of the resource
Returns:
an URL to the resource or null if not found

getResources

public final Enumeration getResources(AgentBase agent,
                                      String name)
                               throws IOException
Finds all the resources with the given name. A resource is some data (images, audio, text, etc) that can be accessed by class code in a way that is independent of the location of the code. The name of a resource is a "/"-separated path name that identifies the resource.
It is searched for in the same way as the classes of this agent (classpath, library dir and package/agent dir)
To support things no longer possible, as access to any classloader is denied.
Parameters:
agent - the agent who wants a resource
name - name of the resource
Returns:
an Enumeration of the resources. If none found, the enumeration is empty
Throws:
IOException -  

getResourceAsStream

public InputStream getResourceAsStream(AgentBase agent,
                                       String name)
Finds the resource with the given name and returns an input stream for reading it. A resource is some data (images, audio, text, etc) that can be accessed by class code in a way that is independent of the location of the code. The name of a resource is a "/"-separated path name that identifies the resource.
It is searched for in the same way as the classes of this agent (classpath, library dir and package/agent dir)
To support things no longer possible, as access to any classloader is denied.
Parameters:
agent - the agent who wants a resource
name - name of the resource
Returns:
an InputStream for reading the resource or null if not found

getAgentContext

protected final AgentData getAgentContext(AgentBase agent)
                                   throws AgentNotRegisteredException
Get the management data of an agent from a supplied reference to it. If not found, throws an exception.
Parameters:
agent - the reference to the agent, for which the data shall be returned
Returns:
the management data of the agent
Throws:
AgentNotRegisteredException - if the agent could not be found in the internal list

getAgentContext

protected final AgentData getAgentContext(AgentIdentity identity)
                                   throws AgentNotRegisteredException
Get the management data of an agent from its identity. If not found, throws an exception.
Parameters:
identity - the identity of the agent, for which the data shall be returned
Returns:
the management data of the agent
Throws:
AgentNotRegisteredException - if the agent could not be found in the internal list

onAgentCreated

protected void onAgentCreated(AgentData data)
Placeholder for updating the user interface after an agent was created. Subclasses overwriting this method MUST call this method in their superclass!
Parameters:
data - the management data of the new agent

onAgentReceived

protected void onAgentReceived(AgentData data)
Placeholder for updating the user interface after an agent was received. Subclasses overwriting this method MUST call this method in their superclass!
Parameters:
data - the management data of the new agent

onAgentPersisted

protected void onAgentPersisted(AgentData data)
Placeholder for updating the user interface after an agent was persisted. Subclasses overwriting this method MUST call this method in their superclass!
Parameters:
data - the management data of the now persisted agent

onAgentDepersisted

protected void onAgentDepersisted(AgentData data)
Placeholder for updating the user interface after an agent was depersisted. Subclasses overwriting this method MUST call this method in their superclass!
Parameters:
data - the management data of the restored agent

onAgentDestroyed

protected void onAgentDestroyed(AgentData data)
Placeholder for updating the user interface after an agent was destroyed. Subclasses overwriting this method MUST call this method in their superclass!
Parameters:
data - the management data of the removed agent

sendMessage

final void sendMessage(AgentBase sender,
                       Message msg)
                throws MessageException
Sends a message to another agent. As the agents are in different classloaders, it is serialized in the sender-classloader and deserialized in the recipient-classloader. If this fails (an contained element is not serializable), an exception is thrown. If the recipient is currently persisted, it will be depersisted and the message delivered afterwards.
Parameters:
sender - the agent who wants to send the message. Must be the same as the sender that is contained in the message.
msg - the message to send
Throws:
UnknownAgentException - if the sender or the recipient is unknown
MessageException - if the sending agent is not the sender of the message
MessageDeliveryException - if the recipient was persisted and could not be depersisted
MessageDeliveryException - if the message could not be (de-)serialized

localBroadcastMessage

final void localBroadcastMessage(AgentBase sender,
                                 BroadcastMessage msg)
                          throws MessageException
Sends a message to all agents in the local system, except the sender and the persisted ones. As the agents are in different classloaders, it is serialized in the sender-classloader and deserialized in the recipient-classloader. If this fails (an contained element is not serializable), an exception is thrown. If the recipient is currently persisted, it will be depersisted and the message delivered afterwards.
Parameters:
sender - the agent who wants to send the message. Must be the same as the sender that is contained in the message.
msg - the message to send
Throws:
UnknownAgentException - if the sender or a recipient is unknown
MessageException - if the sending agent is not the sender of the message
MessageDeliveryException - if the recipient was persisted and could not be depersisted
MessageDeliveryException - if the message could not be (de-)serialized

save

protected String save(String password)
               throws FileNotFoundException
Saves the agent system with all contained agents to the default file. The file is encrypted.
Parameters:
password - the password used for encrypting the file
Returns:
string with errors on all agents, which could not be saved to the file
Throws:
FileNotFoundException - if the file could not be written to

saveAs

protected String saveAs(String filename,
                        String password)
                 throws FileNotFoundException
Saves the agent system with all contained agents to a file. The file is encrypted.
Parameters:
filename - the name of the file to which the system is saved
password - the password used for encrypting the file
Returns:
string with errors on all agents, which could not be saved to the file
Throws:
FileNotFoundException - if the file could not be written to

open

protected String open(String filename,
                      String password)
               throws FileNotFoundException
Reades the agent system with all contained agents from a file. The file is encrypted. All current agents will be terminated before restoring!
Parameters:
filename - the name of the file from which the system is restored
password - the password used for decrypting the file
Returns:
string with errors on all agents, which could not be restored from the file
Throws:
FileNotFoundException - if the file could not be found

reportError

protected void reportError(String msg)
Report an error to the user. This should be done in a visible way, i. e. not to a log-file (which may be used additionally)
Parameters:
msg - the error message to report

getPrice

public Invoice getPrice(AgentBase agent,
                        Permission perm)
Return the price of a permission for an agent. Returns Double.POSITIVE_INFINITY if it is not available to this agent. Value of 0.0 means that this one is free, but must be acquired.
Parameters:
agent - the agent who asks for the price
perm - the permission the agent wants
Returns:
the price of the cheapest permission (the actual permissions might be different if another permission implies the wished one but is cheaper), included in a complete invoice

getSetPrice

public Invoice getSetPrice(AgentBase agent,
                           PermissionCollection perms)
Return the price of a set of permissions for an agent. Returns Double.POSITIVE_INFINITY if any of the requested permissions is not available to this agent.
Parameters:
agent - the agent who asks for the price
perms - the permissions the agent wants
Returns:
the price of the cheapest set of permissions implicating all required permissions (the actual set of permissions might be different if another permission implies the wished ones but is cheaper), included in a complete invoice

buyPermission

public Permission buyPermission(AgentBase agent,
                                Permission perm,
                                Payment payment)
Allows the agent to buy a permission.
Parameters:
agent - the agent who buys the permission
perm - the permission the agent wants
payment - the payment for the permission (must currently be exact the price of the permission)
Returns:
the permission actually granted (might be different if another permission implies the wished one but is cheaper). Null if this permission is not available to the agent.

buyPermissionSet

public PermissionCollection buyPermissionSet(AgentBase agent,
                                             PermissionCollection perms,
                                             Payment payment)
Allows the agent to buy a set of permissions.
Parameters:
agent - the agent who buys the permissions
perms - the permissions the agent wants
payment - the payment for the permission (must currently be exact the price of the set)
Returns:
the permissions actually granted (might be different if another set of permissions implies the wished ones but is cheaper). Empty if any of these permissions is not available to the agent.

returnPermission

public void returnPermission(AgentBase agent,
                             Permission perm)
An agent can return a permission, indicating that he no longer needs it. It will be removed and subsequent checks fail. Basic permissions cannot be returned and will fail silently (no action).
Parameters:
agent - the agent returning the permission
perm - the returned permission

returnPermissionSet

public void returnPermissionSet(AgentBase agent,
                                PermissionCollection perms)
An agent can return permissions, indicating that he no longer needs them. They will be removed and subsequent checks fail. Basic permissions cannot be returned and will fail silently (no action).
Parameters:
agent - the agent returning the set of permissions
perms - the returned permissions

getOptionalPermissions

public PermissionCollection getOptionalPermissions(AgentBase agent)
Returns a collection of all optional permissions. Returned is the set possible, not the one currently granted.
Parameters:
agent - the inquiring agent
Returns:
the set of permissions the agent can possibly acquire (might be empty)

challengeAgent

protected void challengeAgent(AgentData data)
Challenges the agent for the knowledge of its private key. If there is no public key included in the identity of the agent, no challenge takes place. Cuurent status must be NOT_CHALLENGED or nothing will be done.
Parameters:
data - the management data of the agent to challenge
See Also:
PolicyByValue, AgentBase.replyToChallenge(String,byte[])

allowArrivalOfAgent

protected boolean allowArrivalOfAgent(URL whereFrom,
                                      AgentIdentity identity,
                                      CertificateWrapper[] codeSigners,
                                      String agentClass)
Checks whether this agent is allowed to arrive at this host. The code certificates are not checked here, we do not currently have the code so we cannot check if it is really signed with them. This will be done when the first class of the agent is loaded and permissions are assigned. We can check them here if they are plausible and sufficient for at least some permissions.
In this implementation they are completely ignored here.
Parameters:
whereForm - from where the agent arrives
identity - the identity of the agent
codeSigners - array of all certificates, who signed the code
agentClass - name of the main class of the agent
Returns:
true if the agent may arrive

getClassificationStatus

public ClassificationSet getClassificationStatus(AgentBase agent)
Allows an agent to get information on his current status of additional classifications.
Parameters:
agent - the agent which requests its status
Returns:
the set of additional classifications which are currently accepted

getCodeCertificates

public Certificate[] getCodeCertificates(AgentBase agent)
Allows an agent to get information on his accepted code certificates.
Parameters:
agent - the agent which requests its status
Returns:
the list of accepted code certificates

offerAdditionalClassification

public ClassificationSet offerAdditionalClassification(AgentBase agent,
                                                       ClassificationSet offer)
Allows an agent to offer additional classifications to receive more/cheaper permissions.
Parameters:
agent - the agent offering additional classifications
offer - the additional classifications
Returns:
the classifications which were accepted

checkAdditionalClassification

protected boolean checkAdditionalClassification(AgentData agData,
                                                AgentClassification classification)
Checks whether an additional classification is accepted. This might mean a change in permissions or their price. Currenlty only normal certificates are accepted, which reduce the price of permissions to 90% of without them.
Parameters:
agData - the management data of the agent requesting the check
classification - the classification to inspect and verify
Returns:
true if this classification is accepted

dumpClassification

public void dumpClassification(AgentBase agent)
Prints the classification information to System.out. Used for testing purposes only. To be removed for final version.
Parameters:
agent - the agent whose classification should be printed

deploy

public void deploy(AgentData agData)
            throws InvalidKeyException,
                   NoSuchAlgorithmException,
                   SignatureException
Deploys the agent by signing the current state (i. e. the initialization parameters) and the code used if applicable (digest over the code signatures)
Parameters:
agData - the agent to deploy
Throws:
InvalidKeyException - if one of the private keys provided is invalid
NoSuchAlgorithmException - if one of the algorithms provided is unknown
SignatureException - if an error occured during signing or the agent is alread deployed

getAgentIdentityByID

public AgentIdentity getAgentIdentityByID(String ID)
Retrieve the identity of a local agent by its unique ID.
Parameters:
ID - the ID of the agent
Returns:
the identity of the agent or null if not found

storeInReadOnlyStore

public boolean storeInReadOnlyStore(AgentBase requester,
                                    AgentIdentity destination,
                                    Serializable key,
                                    Serializable value)
Tries to store an object under a certain key in the ReadOnlyStore of another agent. To be used for non-repudiable delivery. The destination can just decline it without any reason. Will fail if the recipient has no such store.
Parameters:
requester - the agent wanting to store the value
destination - the identity of the agent, in whichs store to place the value
key - the key under which the value should be stored
value - the value to be stored
Returns:
true if successful, false otherwise (in all cases; regardless whether the recipient has no such store, he declined, or an error occured!)
See Also:
ReadOnlyStore, HasReadOnlyStore, HasVetoableReadOnlyStore

transferObject

protected Serializable transferObject(Serializable obj,
                                      ClassLoader cll)
                               throws IOException,
                                      ClassNotFoundException
Transfers an object from one classloader to another.
Parameters:
obj - the object to transfer
cll - the classloader, to which to convert it
Returns:
the converted object
Throws:
IOException - if the object could not be serialized
ClassNotFoundException - if the object could not be deserialized

acceptPayment

protected boolean acceptPayment(AgentData agData,
                                Payment payment)
Check whether we want to accept this payment for a permission from a certain agent. This implementation verifies the signatures only.
The only accepted ways of payment are creditcard and voucher (must be a FIMVoucher). In addition, an empty payment is allowed, if the price is 0.
Parameters:
agData - the management data for the agent requesting to pay
payment - the payment info to check
Returns:
true if the payment should be accepted
See Also:
FIMVoucher

storePayment

protected void storePayment(AgentData agData,
                            Payment payment)
Store the payment we received for granting a permission in a file. The file used is "payments.txt" in the system directory. The storage format is the XML-encoded form of the payment; new payments are appended to the file. For XML-storing to work, the package containing the parser must be included in the file "privilegedCodeFiles.txt" and must have appropriate permissions granted in the default policy ("java.policy").
Parameters:
agData - the management data for the agent paying
payment - the payment info to store

saveHandOff

protected void saveHandOff(boolean sender,
                           Certificate otherASIdentity,
                           AgentIdentity agentIdentity,
                           byte[] digest,
                           byte[] outSig,
                           byte[] inSig)
Store the hand-off we received (and sent) in a file. The file used is "hand-offs.txt" in the system directory. The storage format is an XML-encoded form of the data; new hand-offs are appended to the file. For XML-storing to work, the package containing the parser must be included in the file "privilegedCodeFiles.txt" and must have appropriate permissions granted in the default policy ("java.policy").
The signed digest includes the name, the class and the identity of the agent, as well as the code-signer certfiicates. Also, the whole package file and the serialized agent are added.
Parameters:
sender - true if we were the sender of the agent, false if we received it
otherASIdentity - the certificate of the other agent system
agentIdentity - the identity of the agent that was transferred
digest - the MD5 digest, which was signed
outSig - the signature we sent to the other system
inSig - the signature we received from the other system

isPrivilegedSource

protected boolean isPrivilegedSource(CodeSource codesource)
Check whether a code is form a privileged package or not. If yes, it will be granted AllPermission. Necessary only for libraries, which are used by the agentsystem (not when used by agents!) and use factory methods (e. g. "Class.forName()") to create objects. These packages must ALSO be included with appropriate permissions in the default policy file (usually "java.policy").
Parameters:
codesource - the codesource
Returns:
true if the code is from a privileged packag
See Also:
PolicyByValue.getPermissions(CodeSource)

main

public static void main(String[] args)
This class can also be used directly to show a GUI-less agent system:
java PkgAgentSystem.AgentSystem agentDir libraryDir [Port [savedFile]]

Agent System POND 1.2 (28.2.2002)

Submit a bug

Copyright 2001,2002 Michael Sonntag & Institute for Information Processing and Microprocessor Technology (FIM), Johannes-Kepler-University Linz, Altenbergerstr. 69, A-4040 Linz, Austria.