Release Note
The SpatialViews Compiler and Runtime System
Version 1.0.1

Contents

1. Copyright and Disclaimer
2. Overview
3. Supported Platforms
4. System Components
5. Setup Instructions
6. Program Examples

Copyright and Disclaimer

This software is distributed for research use only. This software is provided "as is", without warranty of any kind, either express or implied. You agree to bear the entire risk in connection with your use of this software when you download it from this site. The compiler and virtual machine contained in this release are modifications of JDK 1.3.1 and J2ME CLDC 1.0.3 obtained from Sun Microsystems, Inc. under the Sun Community Source License.

Overview

SpatialViews is a Java extension for location-aware progmming in ad-hoc networks. A implementation is provided in this release, which includes the compiler, the runtime system, a configuration tool, and program examples.

A full implementation of the SpatialViews features has been provided since Release Version 1.0, including spatial view definition, spatial view iteration, space granularity (delta s) specification, time granularity (delta t) specification, reduction variable declaration, container variable declaration, and user-defined service registration. These features are illustrated in the program examples included in this release. Release Version 1.0.1 fixed a few bugs.

Limitations

The current implementation has the following limitations.
• The only implemented reduction operation is addtion using the += or ++ operators. The implementation of other reduction operations is going to be supported in future releases.
• Time in a program needs to be specified with a Long integer in milliseconds.
• The compiler only has limited checking for program variable accessibility restrictions. No inter-procedural analysis, pointer alias, or array reference analysis was implemented.

Known Issues

• An iterator with time granularity specified, i.e. an iterator with an "every dt" clause, may experience slow reponse in a setup with more than ten KVMs running on a single PC. Try to keep less than 10 KVMs running on a single PC, if you run into this problem.

Syntax

"spatialview" Ident ["=" [Type] ["@" Expression ["%" Expression]]]
"visiteach" Ident ":" Ident ["every" Expression ("within" Expression|"forever")] Statement
"register" "(" Expression ")" Creator


The spatialview statement defines a spatial view. The visiteach statement iterates over a spatial view. For example,

 spatialview v = Camera @ ConferenceRoomA;
 visiteach x : v { 
   Picture p=x.getPicuture();
   //...
 }

The register statement allocates an object in the node space, and register the object with all the interfaces it implements as its names in the service table on the hosting node. This registration is limited with a lifetime specified in milliseconds. For example,

register(4000) EagerLocationService();

A space granularity (delta s) can be specified in a spatial view definition, using the "%" operator. For example,

spatialview v = LightSensor @ CampusB % 400;

The new modifier "sumreduction" is used to declare a variable as a reduction variable. (This modifier only applies to local variables.) For example,

sumreduction int n;
sumreduction float s;

Supported Platforms

Compilation Platform:

Fedora Core and RedHat 9 Linux

The compiler has been tested on Fedora Core and RedHat 9 Linux. It should also work fine on previous versions of RedHat Linux since version 6.2.

Execution Platform:

Fedora Core and RedHat 9 Linux for Desktops, Familiar Linux 0.7.x and 0.6.x for iPAQs

The SmartMessages Kilobyte Virtual Machine (KVM) has been tested on RedHat 9 Linux for desktops and Familiar Linux 0.7.x and 0.6.x for iPAQs.

System Components

Compiler

The compiler is used almost the same as the original javac 1.3.1 compiler, except that you have to specify a routing scheme with the "-routing" option. The only values available for this option in this release are Flooding and Gossiping. Geographic Flooding will be enforced by the compiler if a space granularity is specified for a spatial view, no matter what value is used in the "-routing" option.

Runtime System

The SpatialViews runtime system includes the SmartMessages Kilobyte Virtual Machine (KVM), its class library, and the SpatialViews class library.

The SmartMessages KVM and its library was originally developed by Porlin Kang as a customized version of the SUN KVM. It is a separate project. We do not maintain the SmartMessages KVM. The SmartMessages KVM and library provide light-weight explicit execution migration.

The SpatialViews class library provides other runtime support for the SpatialViews language that is not in the SmartMessages KVM class library. This library provides basic classes used in every compiled SV program, such as space description, location inquiry, service discovery, and routing.

Configuration Tool

The SmartMessages KVM requires a configuration file. We provide a tool to automatically generate configuration files to run multiple SmartMessages KVMs on one desktop with faked locations. The tool is kvmconfig. It takes as input the number of simulated nodes, the size of the square space, and the radio signal range. It then generates locations for nodes randomly distributed in the space. The network topology is calculated using the given radio signal range. A unit disk radio signal model is used.

The tool kvmconfig is not available for iPAQs. We provide here two examples with manually scripted configurations. The first example assumes static network topology and hard coded locations. There are two iPAQs with IP address 192.168.1.1 and 192.168.1.2 respectively. The configuration file for the first node is ipaq1.conf and for the second ipaq2.conf. Another example uses dynamic neighbor discovery and GPS locations. The configuration file is ipaq_dynamic.conf. Download these configurations, remove the .txt extension, and put one on each node.

Setup Instructions

1. Download all the components in the release, including the compiler and the runtime system.
2. Install the compiler. Run the self-decompressing package of the compiler. You need to make it executable first.

       chmod u+x jdk-1.3.1-spatialviews-xxxxxx-xxxx-linux-i386.sh
       ./jdk-1.3.1-spatialviews-xxxxxx-xxxx-linux-i386.sh
   

   You would get a subdirectory named jdk1.3.1 under your current directory.

3. Install the runtime system. Unpack the gzipped tar file in your home directory, or anywhere else of your own choice.

       tar pzxf svruntime.tar.gz
   

4. Setup environment variables.

       export SVC=<where you decompress the compiler package>/jdk1.3.1
       export SVRUNTIME=<where you unpacked the runtime system>
       export KVMCONFIGS=<the directory where you want to put the configuration files, e.g. $HOME/svconfs>
       export SVAPPS=<where your application classes are going to be,
       e.g. $HOME/svapps/classes>
   NOTE: Don't put '/' in the end of $SVAPPS, i.e. use .../svapps/classes instead of .../svapps/classes/.
   

5. Create configuration files with the automation tool. Issue the following command and answer its questions.

       cd $KVMCONFIGS
       $SVRUNTIME/bin/kvmconfig
   

Program Examples

We provide a few program examples in this release.

Description

HelloWorld (source code)

This program goes to all the nodes in the network and prints "Hello, world!" on each of them.

Count (srouce coude)

This program counts the number of nodes in the network.

CountNear (source code)

This program counts the number of nodes within the range specified at commandline to a location (0,0).

CountSensor (srouce coude)

This program counts the number of nodes providing the Sensor service.

GeoCount (srouce coude)

This program counts the number nodes with a space granuarity.

NestedCount (srouce coude)

This program counts the number of nodes in the network, and for each node counts the number of nodes nearby. A nested iterator is used. Note: the outer iterator may give a result of n less than the real number of nodes in your network. This is because the current implementation of Flooding iteration has an implicit timeout value. Try Gossiping routing by using "make ROUTING=Gossiping" to compile this example. This should give the correct number of nodes in the outer iterator.

AverageLighting (source code)

This program calculates average sensor reading from sensors in the network. (A sensor is a node that provides Sensor service.)

InstallSensor(source code)

This program installs Sensor service on all nodes in the network.

CollectLocations(source code)

This program uses a Container varaible to collect locations of all nodes.

DedicatedLocationService(source code)

This program periodically updates the location service, which is simply provides a fixed location. This location service can be used by any other SpatialViews programs. The CollectLocations example program can collect these locations.

Instructions to Build and Run Example Programs

To try the examples, follow the instructions.
1. Download the examples here, and unpack it.

        tar pzxvf svapps.tar.gz
   

   If you unpack the package in your home directory, set SVAPPS to $HOME/svapps/classes.
2. The previous command will give you a svapps directory. Enter it. Build the classes by issuing make in the svapps directory.

   cd svapps
   make
   

   The default routing is Flooding. Change it to Gossiping by doing

   make ROUTING=Gossiping
   

3. Suppose you have set KVMCONFIGS and run kvmconfig, start the KVMs by issuing command

        $SVRUNTIME/bin/startkvms
   

   This will pop up an xterm window for each KVM.
4. Start a SV program using sm_injector command.

        $SVRUNTIME/smartmessages/bin/sm_injector -p <Port Number>
        <Program> <Program Arguments>
   

   e.g.,

        $SVRUNTIME/smartmessages/bin/sm_injector -p 50001 HelloWorld
        $SVRUNTIME/smartmessages/bin/sm_injector -p 50001 CountNear 80
   

   where HelloWorld.class is a compiled SV program in the Java class format, which is located in the directory specified by $SVAPPS. The port number for each node congigured using kvmconfg is 50001+2*i, where i=0,1,2,...n-1 and n is the number of nodes.
5. If you are done and want to stop all the KVMs, use killall command.

     killall kvm
   

NOTE:
• If you run a SV program, change it and recompile it, you have to kill and restart all KVMs to run the new version, because the KVM caches code.
• If a service is needed, you can install a service on a node using the following command.

  $SVRUNTIME/smartmessages/bin/sm_injector -p <Port Number> ServiceTable <Service> <Implementation>
  

  e.g.,

  $SVRUNTIME/smartmessages/bin/sm_injector -p 50003 ServiceTable Sensor RealSensor