How to run Zanshin simulations

To run Zanshin simulations there are two things to do: execute Zanshin inside Equinox, the OSGi container that comes with Eclipse, and executing the Simulation Console, an external application that allows you to run the simulations.

To do so, you need to have Eclipse installed and running, with Zanshin's projects downloaded and opened in the workspace. If you haven't done so already, follow the instructions at the How to download Zanshin wiki page.

Running the Zanshin Server

Zanshin can be run as a server that accepts connections from external applications which would like to take implement adaptivity based on the framework's feedback loop architecture. To do so, follow the steps below:

1. Click the menu Run -> Run Configurations...;

2. At the left-hand side of the Run Configurations window, select the OSGi Framework item and click the New launch configuration button at the top of the list (first button on the left). A new configuration is created and opened at the right-hand side of the window;

3. Fill in the Name field with a name for your run configuration (e.g., Zanshin);

4. At the Bundles tab, click the Deselect All button at the right of the list and then mark all it.unitn.disi.zanshin bundles shown in the list under the Workspace category;

5. Some Zanshin bundles depend on others. To guarantee proper wiring of dependencies (until I figure out how to do this automatically), set the start level of the core bundle to 3 and of the logging bundle to 2. This can be done by clicking on the word default under the Start Level column, next to the bundle's names;

6. In order to add all required dependencies, click the Add Required Bundles button (straight below this button there is a count of selected bundles that should say something like 44 out of 667 selected);

7. Click Apply, then Run.

You should see many logging messages in Eclipse's Console view. Just to give an idea, these are the informational messages printed by Zanshin v0.92 when started (other messages were deleted on purpose, this is just to give you a reference):

[zanshin.logging          ] INFO: BundleEvent STARTED
[zanshin.core             ] INFO: Zanshin Core Component starting...
[zanshin.core             ] INFO: ServiceEvent REGISTERED
[zanshin.core             ] INFO: ServiceEvent REGISTERED
[zanshin.core             ] INFO: BundleEvent STARTED
[zanshin.adaptation       ] INFO: Zanshin Adaptation Component starting...
[zanshin.adaptation       ] INFO: ServiceEvent REGISTERED
[zanshin.adaptation       ] INFO: BundleEvent STARTED
[zanshin.adaptation.qualia] INFO: Zanshin Adaptation Sub-component "Qualia" starting...
[zanshin.adaptation.qualia] INFO: ServiceEvent REGISTERED
[zanshin.adaptation.qualia] INFO: BundleEvent STARTED
[zanshin.monitoring       ] INFO: Zanshin Monitoring Component starting...
[zanshin.monitoring       ] INFO: Monitoring thread started...
[zanshin.monitoring       ] INFO: Adaptation Service injected in the monitoring thread.
[zanshin.monitoring       ] INFO: Repository Service injected in the monitoring thread.
[zanshin.monitoring       ] INFO: Monitoring Service injected in this bundle
[zanshin.monitoring       ] INFO: ServiceEvent REGISTERED
[zanshin.monitoring       ] INFO: BundleEvent STARTED
[zanshin.controller       ] INFO: Zanshin Controller Component starting...
[zanshin.controller       ] INFO: Model Management Service injected in the RMI server
[zanshin.controller       ] INFO: Repository Service injected in the RMI server
[zanshin.controller       ] INFO: Zanshin Server injected in this bundle
[zanshin.controller       ] INFO: Zanshin Controller Component has started its server.
[zanshin.controller       ] INFO: Repository Service injected in the RMI Target System Controller Service
[zanshin.controller       ] INFO: Zanshin Server injected in the RMI Target System Controller Service
[zanshin.core             ] INFO: Target System Controller Service injected in this bundle
[zanshin.core             ] INFO: Repository Service injected in the activator
[zanshin.core             ] INFO: Monitoring Service injected in the activator
[zanshin.core             ] INFO: Reconfiguration Service added to this bundle: qualia
[zanshin.controller       ] INFO: ServiceEvent REGISTERED
[zanshin.controller       ] INFO: ServiceEvent REGISTERED
[zanshin.controller       ] INFO: BundleEvent STARTED

To exit Zanshin, click the Console view, type exit and press Enter twice or click on the red square (stop) button to force Equinox to quit. To run Zanshin again, just click the menu Run -> Run History -> Zanshin (replace Zanshin with whatever name you gave to the run configuration).

Running the Simulation Console

Once the server is running, you can execute also the simulation console, which loads the simulations configured in the /zanshin-simulations/src/it/unitn/disi/zanshin/simulation/simulation.properties file and allows you to execute them.

To run it, locate the class it.unitn.disi.zanshin.simulation.Main in the zanshin-simulations project, right-click on it and select Run As -> Java Application. This will run the simulations console also inside Eclipse, sharing the Console view with Zanshin (one of the buttons in this view switches from one running application to another).

When ran, the Simulation Console should display the following messages (which may be intertwined with logging messages):

残心へようこそ (Welcome to Zanshin!)
Initializing simulations, please wait...
Done. If you need assistance, use the 'help' command.

Type help (and press Enter) to view the available commands and learn how to run simulations.

A better set-up for following the simulations

Having Zanshin and the Simulation Console dividing the same view of Eclipse can be confusing or annoying. The following explains how to divide them in three views: Zanshin's log, Simulation Console and Simulation Console's log.

Separating the console from Zanshin is easy: open a terminal (command prompt on Windows), navigate to the directory of the zanshin-simulations project (if you don't know where it is, right-click the project in Eclipse, ask for Properties and look for the Location information in the Resource page) and use the following command:

java -Djava.util.logging.config.file=logging.properties -cp lib/zanshin-remote.jar:bin/ it.unitn.disi.zanshin.simulation.Main

(Windows users might have to separate the classpath using semicolons instead of colons: lib/zanshin-remote.jar;bin/)

The -Djava.util.logging.config.file=logging.properties option tells Java's logging framework to use the configurations supplied in this file, which is at the root of the zanshin-simulations project. This file instructs the logging framework to send logging information to a file called zanshin0.log in your system's temporary directory. The location of this directory changes from system to system. Check out this blog post for a simple way of finding out where the temporary directory is in your operating system.

Now Eclipse's console will show only Zanshin's log (where you can see what happens in the adaptation framework), the terminal you opened will serve only to issue commands to the Simulations Console, without any logging message getting in the way. Finally, by monitoring the zanshin0.log file you can see what happens in the managed system's side (or target system as I call it in my research). To monitor the log file in real time, use the tail utility in Linux/Mac or Tail for Win32 if you use the Microsoft OS:

tail -f zanshin0.log