Install Notes

1. Download POEMA0.1. You can save the downloaded file anywhere on your local disk.
Installation requirement: JavaTM 2 SDK, v 1.3 or the JavaTM 2 Runtime Environment, v 1.3; Micorsoft Windows 95/98/2000 or Windows NT4.0 or greater.

2. Uncompress and extract the downloaded file (use the WinZip utility). This will create a directory named POEMA, with several subdirectories. By default, the POEMA directory will be created in the same directory as the downloaded file.

3. The directory extracted in the previous step contains a subdirectory named "Library". It contains the PonderTk.jar and the sub-directory "lib". All this content must be copied in the current JRE, under the standard local code source:

<java-home>\jre\lib\ext
   

4. To run the framework, exec the file RunPOEMA.bat stored under the directory POEMA.

How to run the Demo

POEMA prototype contains a simple example ready to run. 

System Configuration 
Monitoring Configuration
Policy Management Console
Agent Launch
A simple policy-controlled agent

 

DOWNLOAD POEMA0.1

  

Enjoy POEMA0.1!

System Configuration

First Installation

The first installation ofthe POEMA system requires to model a network configuration. To this purpose, POEMA exploits SOMA facilities (see SOMA). A Place abstraction represents an agent execution environment and can model a physical node. The Domain abstraction encloses a set of places and it typically represents a LAN. Each Domain includes a gateway, called Default Place, that is in charge of provide connections between different domains.

The Demo requires a configuration composed by two Places within the same Domain: Place "Italia" that acts as the Default Place and the Place "Roma" that represents an ordinary Place. The creation of these Places is required only at the first execution of POEMA framework through the 'Advanced Configuration Windows' which is a graphical interface automatically opened at the first execution.

The Place abstractions can be created locally on the same machine for a centralized simulation or on different machines for a distributed simulation.

At the end of the configuration, the Place hierarchy shown in the Configuration Window must be as the following:
The specified network configuration is stored on filesystem and can be used by the user also for next working sessions. For any further information about the system configuration, please refer to SOMA.

BACK

Monitoring Configuration

The Monitoring Service integrated in POEMA provides several functionalities. First of all it monitors and controls the consumption of some resources for each executing process and agent, then it reports some statistics about the current values of monitored consumption and finally it provides the notification of an alarm event to the Event Dispatcher when the value of a monitored resource goes over a certain threshold. The threshold can be graphically selected by the users.

The Monitoring Service can be actived and configured through the use of a simple graphical interface called "Place Resource Manager". To open the window, select 'PlaceResourceManager' from the 'Place' Menu provided at each Place window. Only one Monitoring Service can be actived for each Place.

The radio button 'Start' ('Stop') at the head of the window is used to start (stop) the execution of the Monitoring Service.

The radio button 'On' ('Off') at the bottom of the window is used to enable(disable) the notification of an event to the Event Dispatcher when the consumption of the monitored recourses go over the threshold selected for the resources.

Moreover, the window provide other five functionalities:

  1. Agent Monitor button: it opens a window that shows the current agents in execution on the Place. For each of them, their current consumption value of the CPU and the memory of the machine, together with the number of Input TCP packets, Output TCP packets, Input UDP packets, Output UDP packets, read files, read files is provided.
  2. Process Monitor button: it opens a window that shows the current process in execution on the Place, together with the level of their current CPU and memory consumption.
  3. Network Monitor button: it opens a windows that reports statistics about the current network traffic of the machine.
  4. Consumption Threshold button: it opens a window that provides the possibility to view and select the current threshold values.
  5. Alarm Number button: it opens a window that reports statistics about the number of generated events.

BACK

Policy Management

Ponder Policy Editor

To run the Policy Editor, select 'Launch Ponder Toolkit' from the 'Configuration' Menu. The Ponder Toolkit window will be opened and it is possible to edit and compile a Ponder policy into a java class file by pressing the 'Policy Editor' button. For more details, see the Quick guide from Ponder documentation.

POEMA v 0.1 supports only Obligation Policies.

Policy Management Console

After the creation of mobility policies policy, users can manage them by using the 'Policy Management Console' interface. A 'Policy Management Console' window can be opened from any Place in which users are working, by selecting 'Policy Management' from the 'Configuration' Menu of the Place Window.

The Policy Management Console interface is composed by three parts.

In the upper-left side of the Policy Console window, the set of compiled policies that are visible from the current place are shown. Details about policies (name, kind, subject...) can be viewed in the upper-right side of the window, simply by clicking one time on the interesting policy. On the bottom of the window there are buttons to manage the policy life-cycle, accordingly to the following SFA:

Each button sends a command to the Policy Coordinator that provides the management of the policy state in a centralized way.

For example, the button "Query Pol.Status" send a query about the policy state to the Coordinator , which will respond with the current state of the policy. To Load/Unload/Enable/Disable a policy, click the correspondent button in the bottom side of the Policy Console window. The request is submitted to the Policy Coordinator that automatically provides to manage it.

Policy Coordinator

The Policy Coordinator implements the Policy Management Service and is a stationary and centralized service always running on each Default Place of Poema system. It provides the distribution of the policies to the interested entities and the management of the Control Objects of the policies.

It waits for :

  1. arrivals of external commands for policy management
  2. notifications about the beginning of agents execution inside its administered domain

In the first case, at any command occurrence, the Coordinator tries to execute it accordingly to the policy life cycle. For example, if the request is a query abut the state of a certain policies it retrieves the Control Object of the policy from its local database, it reads the current state and finally it notifies it to the sender of the request command. Otherwise, if the request is a command to Load/Unload/Enable/Disable a policy, it retrieves the Control Object of the policy from its local database and then tries to execute the command with the following steps:

  1. It controls that the request to perform is coherent with the policy state (i.e., a policy can not be loaded twice);
  2. It updates the Control object of the policy;
  3. Accordingly to the received command , it loads/unloads/enables/disables the policy on the agent that is the subject of the policy if the agent is currently in execution; otherwise it wait the starting of the agent execution for updating its policy set;
  4. It forces the agent subscription for the triggering event of the policy to the Event Service ;
  5. It replies to the sender of the command with a notification about the correct execution of the command or an error message

The activity of the Policy Coordinator and its set of managed policies can be observed from the outside through the Coordinator GUI window. This window can be opened only in the Default Place by selecting 'Show Coordinator GUI' from the 'Place' menu. Anyway, the Policy Coordinator activity can only be observed and never altered by the Coordinator GUI window.

In the Upper side of the Coordinator GUI window there is the list of current Obligation Control Objects managed by the Policy Coordinator, ordered by name of the policy subjects. The lower side of the window reports service messages about the Coordinator activity.

In the example of the picture, the polices 'TimePolicy1 and TimePolicy2' are currently managed by the Policy Coordinator. The subject of both the policies is the agent called 'Italia 1'. TimePolicy2 is currently in the DORMANT state, while the TimePolicy is in the ENABLED state. Therefore the TimePolicy1 will be loaded on the 'Italia 1' agent as soon as it starts executing. The Coordinator waits for the notification about the creation of new agents within its administrative domain. When the agent 'Italia 1' begins to run, it notifies the beginning of its execution to the Coordinator that provide to update the agent with its policies.

BACK

Agent Launch

How to launch an agent

Agents can be launched from any Poema Place. To Launch one of the pre-compiled agents that are stored inside the directory POEMA/agents, press the 'Launch Agent' button. The selection of the agent to be launched can be made from a graphical list as shown in the following pictures.

 

At the bottom of the 'Agent Launch' window, three check-boxes provide the possibility to select launching options:

Therefore, remember to always select the 'With Policy' check-box to assure a policy support for any policy-controlled agent.

The 'PolicyControlledAgent' agent

The 'PolicyControlledAgent' agent is an example of policy-controlled agent. Remember to check the 'With Policy' checkbox when launching the agent to provide the policy support to it.

By the graphical interface of the agent, it is possible both to command the agent do some action and to control its current set of mobility policies. For example, user can command the agent to migrate to a certain Place('GoTo' button) or to come back to its home Place ('Home' button), to send an mail communication to other agents ('Send' button) or to get information details about the current Place of execution('Place' button).In addition, the set of current mobility policies of the agent can be viewed by selecting 'Policy' from the 'Info' menu.

The figure shows that just one policy ('TimePolicy1' Obligation policy) is currently loaded on the agent, and some details of the policies are provided to users.

BACK

A Simple Policy-controlled Agent

The demo consists in controlling the migration of the 'PolicyControlledAgent' with Ponder obligation policies. In particular, two policies are furnished with the Demo, and ready to be used.

The TimePolicy1 is triggered every minute and forces the migration of the agent called "Italia1" (the first agent that has been created in Place "Italia") to the Place "Italia" if the agent is currently executing on Place "Italia Roma".

The TimePolicy2 is triggered every minute and forces the migration of the agent called "Italia1" (the first agent that has been created in Place "Italia") to the Place "Italia Roma" if the agent is currently executing on Place "Italia".

So, when both the policy are enable to the agent, the agent is forced to go and come back between the Places 'Italia' and 'Italia Roma'.

To see the agent in execution, please use a system configuration as indicated in the SystemConfiguration section and follow these steps:

  1. Launch the agent as indicate in the AgentLaunch section. Remember to check the 'With Policy' checkbox when launching the agent to provide the policy support to it. Important: the policy subject for both the policies is the first agent created on Place 'Italia' ('Italia 1' agent). So the PolicyControlled agent to be tested must be the first agent created on the Place "Italia";
  2. Load and then enable the pre-compiled policies 'TimePolicy1' and 'TimePolicy2' that are furnished with the Poema system on the agent;
  3. Control that both the policies are enabled on the agent, by selecting the ' Policy' button from the 'Info' menu;
  4. Start the monitoring service as described in the Monitoring Configuration section. If both the policy are enabled, the agent starts to go and come back between the 'Italia' Place and the 'Italia Roma' Place at every minute.

Alternatively, it is possibile to manage the policies also before the agent launching.

Note: The provided policies (TimePolicy1 and TimePolicy2) are written for the first agent that is launched on Place "Italia" (the subject field of the policy is "Italia_1"). To control other agents with similar policies is very simple. For example, it is possible to control the mobility of an agent called "Italia Roma 2", simply by writing a new policy in which the subject field is "/Italia_Roma_2" and then compile it.

Notes: it is worth noting that the POEMA v.0.1 allows only to specify predefined events. This is due to the fact the POEMA v.0.1 integrates the Ponder toolkit v.0.1 that allows only to define events that the Ponder library makes available. The new POEMA version with the new Ponder toolkit that permits to enlarge the Ponder event library with application-specific events will be soon available.
 
In case of problems, or if you find any bug, please contact us.