SAF manual. September 21, Overview License and copyright Requirements Getting started Credits...

Transcription

1 SAF manual September 21, 2008 Contents 1 Overview License and copyright Requirements Getting started Credits Download instructions 3 3 Location server users guide Description Deployment and configuration Configuration file Location model Customization Measure types Proximity measures Geometric measures Symbolic measures Hybrid measures Measure communication format Concepts Formal syntax Example Context server users guide Description Deployment and configuration Defining inference rules Adaptation framework users guide 16 1

2 5.1 Description Adaptation library Push library RFID driver users guide 21 7 GPS driver users guide 21 8 Developers Guide MAVEN instructions Installing the package and prepare the built environment Compile the code Generate the documentation Generate the source and binary packages Note on local MAVEN repository Overview SAF (Situation Aware Framework) is the component of the NAMGIS framework responsible for detecting, integrating and processing context data, in order to support application in implementing context-aware functionalities. SAF is a Java framework composed of several components: a Location Server, responsible to acquire location data (the most relevant context data) a Context Server, responsible to integrate location data with other kinds of context data provided by the application an Adaptation Framework, responsible to provide context-aware adaptation facilities to Web applications drivers to collect location data from RFID readers and GPS receivers 1.1 License and copyright All the components of SAF are released under an GPLv3 license. SAF is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. 1.2 Requirements To use the software you need a JDK 1.5 or newer installed on your machine. While SAF server code is targeted at J2SE, the framework contains also drivers targeted at mobile devices running Java J2ME CLDC 1.3.1: you need a compatible device in order to run these drivers (if you own a Pocket PC you have also the option, recommended, to use the.net version of these drivers you can find on the NAMGIS Web site). SAF project structure is based on MAVEN; in order to compile the package or change the code you need to download and configure MAVEN on your machine (see for detailed instructions). 2

3 1.3 Getting started Please refer to the following sections for information regarding SAF components: Location server users guide Context server users guide Adaptation framework users guide RFID driver users guide GPS driver users guide If you want to compile the code or extend the tool, please refer to the developer guide. 1.4 Credits SAF is the result of the research work carried out at CEFRIEL in the context of MAIS Italian research project (Firb) and subsequently while supporting the group at Dipartimento di Geomatica of Politecnico di Milano in the context of the ArcheoMedSat Italian research project. 2 Download instructions SAF source code and binaries can be downloaded together with other NAMGIS components from the Web site of Laboratorio of Geomatica at Politecnico di Milano: SAF is distributed as several packages: an all-inclusive source package, containing the source code for all SAF components; download this package if you need the source code or if you want to compile the components on your own. a location server binary package, containing the compiled binaries of the location server; download this package if you just want to configure and run a location server on your machine. a context server binary package, containing a ready to start binary distribution of the context server. an adaptation library binary package, containing the JARS of the WEB-ECA (and of the Pusher) framework that you can use to build your context-aware Web application. an RFID driver binary package, containing the Java application you can use to drive an RFID reader on a Pocket PC device, in order to collect proximity measures and send them to a location server. a GPS driver binary package, containing the Java application you can use to drive a GPS receiver on a Pocket PC device, in order to collect geometric measures and send them to a location server. The source package includes also local MAVEN repository (/mvnrepo) containing JAR files for the Java JTA library, the Pushlet, the RXTX serial port Java driver and for the Prevayler persistence library; these packages were not available on public MAVEN repositories at the time SAF packages were built. Finally a note regarding the RFID and GPS drivers. These applications have been written in Java so they should run on every platform that supports at least Java J2ME CLCD 1.3 or greater; however, the serial port driver (we use RXTX) is platform specific and this is the reason we provide these binary packages only for the Pocket PC platform. You can however use these applications with other platforms, provided you replace the shipped RXTX JARS with the ones compatible with the target platform. 3

4 3 Location server users guide The location server is the component responsible to acquire raw location data from sensors and produce estimates of current users positions. 3.1 Description The location server component is realized as a standalone Java server application, which listens for incoming measures and process them according to a pipes & filters approach. The location server collects raw location measures from sensors using sensor drivers (which are usually standalone processes that sends stream of measures to the server). The location server processes these measures by means of a pipeline and collect the estimates of users positions which are then made available to external processes. Internally, the location server adopts a module approach and allows several modules to be arranged to form a pipeline where measures are acquired and processed. Three types of modules build this pipeline: source modules; a source is in charge to collect measure from external sources (usually by interacting with a sensor driver). filter modules; a filter is in charge to process a stream of measures coming from sources and other filters; during this processing a filter can change the measure, translate it or perform whatever operation that takes the measure as an input. output modules an output module can act on a stream of processed measures; these modules are used to keep track of computed users positions and to make them available to external applications. 3.2 Deployment and configuration The binary packages contains all the files needed to execute a location server on your machine. You have simply to download and extract the package on a folder on your system, and then follow these instructions: Create the user and the databases needed by the location server. Using the PostgreSQL client, you have to: create a user saf with password saf ; create a location database using the postgis template (we suggest the name saf-location, but you can change it freely), then execute the script create db.sql to initialize the tables. create an ips database using template0 (we suggest the name saf-ips, but you can change it freely), then execute the script create ips db.sql to initialize the tables. Define and load a location model into the server. A location model is an XML file listing the symbolic locations, objects and connections that constitute the environemnt of interest, together with their relationships and geographical perimeters. Please refer to the location model section for more details. Import the location model using the import script: import <full_path_to_model_file> Configure the location server, by editing the file /conf/location-server.xml Please refer to the template location-server.xml included in the binary package for more details on this process. Start the location server, by running the run script in the /bin folder: run.bat 4

5 3.3 Configuration file The following box shows the structure of the configuration file used by the location server with instructions on how to edit it. You can file this template in the binary package; you have to edit it before launching the location server. <?xml version="1.0" encoding="utf-8"?> This is the configuration file of the location server. Please edit this file following the instructions given inline before starting the server. <locationserver xmlns=" xmlns:xsi=" xsi:schemalocation=" xsd-non-originale.xsd" name="location Server" udpdiscoveryport="12000" rmiregistryport="12001"> The properties here defined are available to every module configured in the system. <property name="sample_property">value_of_sample_property</property> Edit the following section with the correct connection settings of the location database. <locationmodel> <datasource driverclassname="org.postgresql.driver" url="jdbc:postgresql://localhost:5432/location" username="location" password="location" sqldialect="postgresql" /> </locationmodel> Edit the following section with the correct connection settings of the user database (this could be the same location database) <userregistry> <datasource driverclassname="org.postgresql.driver" url="jdbc:postgresql://localhost:5432/nomadic-location" username="nomadic" password="nomadic" sqldialect="postgresql" /> </userregistry> This section configures the source modules for the location server. Add a source element for each source you want to configure. By default, only the NetworkCollector source is instantiated. You have to specify the source class, an identifying name, whether the source is thread safe, what to do in case of error (ignore, delayed_restart, shutdown). You can also specify custom properties which depends on the particular source instantiated. <sources> <source name="networkcollector" class="it.cefriel.location.server.modules.sources.networkcollector" threadsafe="true"> <property name="tcpport">12012</property> 5

6 <property name="udpport">12013</property> <error class="java.lang.throwable" action="delayed_restart" /> </source> </sources> This section configures the filter modules for the location server. Add a filter element for each filter you want to configure. Filter configuration is similar to source configuration, but you have also to bind filter output ports to other filters, by using the port element and the nested connectedfilter or connectedexit elements. <filters> This filter is the entry point (it uses the special name entry ) and takes every input measure and log it to a log file, then forwards them to the dispatcher filter. <filter name="entry" class="it.cefriel.location.server.modules.filters.measurelogger" threadsafe="true"> <property name="fields"> type, ts, src, cs, var, lat, long, alt, ns, nbl, npo, nc </property> <property name="filename">measures.log</property> <port name="output"> <connectedfilter name="dispatcher" /> </port> </filter> This filter dispatch incoming measures to one of the configured downstream filter, according to their type. <filter name="dispatcher" class="it.cefriel.location.server.modules.filters.measuredispatcherfilter" threadsafe="true"> <port name="geometricmeasure"> <connectedfilter name="transformer" /> </port> <port name="hybridmeasure"> <connectedfilter name="transformer" /> </port> <port name="proximitymeasure"> <connectedfilter name="ips" /> </port> </filter> The transformer filter can be used to transform incoming geometric measures from a reference system to another one. The filter applies a linear transformation defined by specifying the correspondences between three pairs of points. The following configuration specifies an identity mapping which performs no transformation at all. The resulting measures are finally forwarded to the gps filter. <filter name="transformer" 6

7 class="it.cefriel.location.server.modules.filters.lineartransformer" threadsafe="true"> <property name="input0">[0.0, 0.0]</property> <property name="output0">[0.0, 0.0]</property> <property name="input1">[1.0, 0.0]</property> <property name="output1">[1.0, 0.0]</property> <property name="input2">[0.0, 1.0]</property> <property name="output2">[0.0, 1.0]</property> <port name="output"> <connectedfilter name="gps" /> </port> </filter> This filter maps incoming geometric measures to symbolic locations by looking up the basic location that contains the detected coordinates from the spatial PostGIS location database. Output measures are of hybrid type (they are both geometric and symbolic) and they are forwarded to the exit point of the filter pipeline. <filter name="gps" class="it.cefriel.location.server.modules.filters.geometricfilter" threadsafe="true"> <port name="output"> <connectedexit /> </port> </filter> This is the IPS filter which interprets proximity measures according to an FSM approach. It tracks users moving in the environment and produces symbolic measures carryng the symbolic location of the user. In order to use this filter you have to create an IPS database under PostgreSQL and configure here the connection parameters. <filter name="ips" class="it.cefriel.ips.filter.ipsfilterimpl" threadsafe="true"> <property name="databasedriver">org.postgresql.driver</property> <property name="databaseurl">jdbc:postgresql://localhost:5432/ips</property> <property name="databaseusername">ips</property> <property name="databasepassword">ips</property> <property name="databasesqldialect">postgresql</property> <property name="sensorsupdatedelay">0</property> <property name="usersupdatedelay">60000</property> <error class="java.lang.throwable" action="delayed_restart" /> <port name="output"> <connectedfilter name="hybrid" /> </port> </filter> This filter takes the output of the ips filter, which are symbolic measures, and compute an estimate of the user coordinates by assigning the coordinates of a central point of the detected symbolic location. <filter name="hybrid" class="it.cefriel.location.server.modules.filters.symbolictohybridfilter" 7

8 threadsafe="true"> <port name="output"> <connectedexit /> </port> </filter> </filters> This section configures the output modules for the location server. Output modules receive the measures processed by the filters and can act on them. By default, an API output module and a GPS output module are instantiated. The first collects location estimates and provides them to remote application using the location API. The second is necessary in order to support the GPS learning procedure. <outputs> <output name="apioutput" class="it.cefriel.location.server.modules.outputs.apioutputimpl" threadsafe="true"> <error class="java.lang.throwable" action="ignore" /> </output> <output name="gpsoutput" class="it.cefriel.ops.learning.gpsoutputimpl" threadsafe="true"> <error class="java.lang.throwable" action="ignore" /> </output> Uncomment these lines for the integration with the context server <output name="contextserviceoutput" class="it.cefriel.context.ext.contextserviceoutput" threadsafe="true"> <property name="serverurl"> rmi://localhost:1099/context-service </property> <error class="java.lang.throwable" action="ignore" /> </output> </outputs> </locationserver> 3.4 Location model A location model is required in order to define the structure of the environment. The model should be loaded into the location server before it can be started the first time. 8

9 The location model. The following box shows a template location model; you can find it in the binary package. <?xml version="1.0"?> This file is an example of a location model that can be loaded into the location server. In order to use the location server you need to define and load a model beforehand. <context xmlns=" xmlns:xsi=" <environment> <locationmodel> Here you can define location categories. Each category has an ID, a name and an optional description. You have to add a locationcategory element for each desired category. <locationcategories> <locationcategory id="1" name="all-locations"> <description>generic location category</description> </locationcategory> </locationcategories> Here you can define object categories. Each category has an ID, a name and an optional description. You have to add an objectcategory element for each desired category. <objectcategories> <objectcategory id="2" name="all-objects"> <description>generic object category</description> 9

10 </objectcategory> </objectcategories> This section defines the location tree. Internal nodes are compound locations; leaf nodes are basic locations. Each node has an id, a name and an optional description. For basic location nodes you can also list the physical objects contained by the locations. <compoundlocation id="100" name="root-location" category="1"> <description>root location</description> <compoundlocation id="101" name="child-location" category="1"> <description>child location</description> <basiclocation id="102" name="leaf-location-1" category="1"> <description>first basic location</description> </basiclocation> <basiclocation id="103" name="leaf-location-2" category="1"> <description>second basic location</description> <physicalobject id="200" name="object-1" category="2"> <description>an object</description> </physicalobject> </basiclocation> </compoundlocation> </compoundlocation> This section defines the connections between basic locations. Each connection is identified by a numerical ID and have to specify the IDs of the two connected basic locations. You have to add a connection element for each connection you want to define. <connections> <connection id="300"> <connectedlocation ref="102" /> <connectedlocation ref="103" /> </connection> </connections> </locationmodel> </environment> </context> 3.5 Customization You can extend the location server component in four different ways: You can provide new drivers in order to acquire location data from new sensor devices. There are no particular requirements on the driver, apart the interface to be used to send measures to the location server. To this end, we reccomend the use of the default NetworkCollector source (class 10

11 it.cefriel.location.server.modules.sources.networkcollector), which adopts a simple TCP/IP based communication protocols. Using this source you can simply open a TCP connection and start sending a stream of measures as text data to the location server. You can however implement your own source in order to use a custom communication protocol between the driver and the location server, or in order to provide a type of measure not predefined by the system. You can provide new source modules that collect measures and feed them into the location server pipeline. To do this you need to implement the it.cefriel.location.server.modules.source interface, compile your classes, place the resulting JAR on the location server /lib folder and edit the location server configuration file in order to instantiate your new source. You can provide new filter modules to include in the location server pipeline in order to process a stream of measures (e.g. to convert from one measure to another, more higher-level one). To do this you need to implement the it.cefriel.location.server.modules.filter interface, compile your classes, put the resulting JAR in the location server /lib folder and edit the server configuration file in order to instantiate your new filter. Finally, you can provide new output modules to act on the processed stream of measures produced by the location server. This can be done by implementing interface it.cefriel.location.server.modules.source; compiled JAR should be placed in the /lib folder of the server and its configuration file should be edited in order to instantiate the module. 3.6 Measure types The following types of measures are supported by the location server. You can use them while sending sensor data to the server. You can also extend them, but in this case you will be required to provide your own modules to collect, process and act on these measures Proximity measures A proximity measure signals that a source sensor (possibly the one that produced the measures) is near to a given set of sensors (possibly empty). This measure represent the current situation of the source sensor: all the sensors listed are assumed to be near the source sensor; all the sensors not listed are assumed not to be near. Please note that this measure does not provide any indication about the actual distance between the source and the other listed sensors. The very concept of near to depends here on the particular sensor technology or application (e.g. for RFID, a reader is considered to be near to all the tags detected during a read cycle). Property Cardinality Type Description type 1 string type of measure (=measure.proximity) ts 0..1 long measure timestamp src 1 string sensor id using the format category.id ns 0..* string a detected sensor (format category.id) Geometric measures A geometric measure reports the geographical coordinates of the source sensor, according to a particular reference system defined using a string (currently only WGS84 is supported). Coordinates are latitued and longitude, which are required and expressed in degrees, and optionally the altitude, expressed in meters. The measure includes also a variance field that can be used to specify a variance computed on the basis of the latitude and longitude (this datum is not used at the moment). 11

12 Property Cardinality Type Description type 1 string type of measure (=measure.geometric) ts 0..1 long measure timestamp src 1 string sensor id using the format category.id cs 0..1 string reference system name (=WGS84) var 0..1 double the variance of the measure long 1 double the longitude in degrees lat 1 double the latitude in degrees alt 0..1 double the optional altitude in meters Symbolic measures A symbolic measure encodes the symbolic location of a source sensor. This kind of measure specifies the basic location which contains the sensor, together with the near objects and connections. For each of these the measure can report the probability on a scale Property Cardinality Type Description type 1 string type of measure (=measure.symbolic) ts 0..1 long measure timestamp src 1 string sensor id using the format category.id nbl 0..* string a basic location, in the format code:probability npo 0..* string a near physical object, in the format code:probability nc 0..* string a near connection, in the format code:probability Hybrid measures An hybrid measure represents both the symbolic location and the geographical coordinates of a source sensor; this measure is thus a mix of a geometric measure and a symbolic one, and its properties are the union of the properties of these two kinds of measure (except the reference system which is assumed to be WGS84). Property Cardinality Type Description type 1 string type of measure (=measure.hybrid) ts 0..1 long measure timestamp src 1 string sensor id using the format category.id var 0..1 double the variance of the measure long 1 double the longitude in degrees lat 1 double the latitude in degrees alt 0..1 double the optional altitude in meters nbl 0..* string a basic location, in the format code:probability npo 0..* string a near physical object, in the format code:probability nc 0..* string a near connection, in the format code:probability 12

13 3.7 Measure communication format This section describes the format used to encode a stream of measures when transmitted to the location server over a TCP/IP connection. This format has been designed with interoperability in mind and can be also used to store measures on a file. This is a textual format, not based on XML because it should be used also on small devices with little CPU power Concepts The format supports the encoding of any measure that respect the following data model (encoding rules are provided in the following subsection). A measures is defined as an ordered sequence of key-value properties, where: the key represents the name of a property and it is an alphanumeric string composed of digits, letters and the dot character. a value is an arbitrary string containing no newline character (so it is constrained to be a single-line string). a key can be shared by several key-value pairs; this situation occurs for properties with multiple values; the order of these occurrences is relevant and permit to associate to the property a list of values. there is a special key type whose unique value specifies the kind of measure encoded (see the previous measure types section) Formal syntax The format allows the encoding of a generic sequence of measures whose data can be expressed according to the data model defined above. A document respecting this standard can define a list or zero or more measures, can contain comments and satisfies the following EBNF syntax: Terminals: CHARACTER := a generic character exluded \n (newline) ALPHANUMERIC := a letter or digit SPACE := the space or horizontal tab characters COMMENT := the # character COLON := the : character DOT := the. character NEWLINE := the \n character Derivation rules: document => (blank_line comment_line measure_block)* blank_line => SPACE* NEWLINE comment_line => SPACE* COMMENT CHARACTER* NEWLINE measure_block => key_value_line* NEWLINE key_value_line => SPACE* key SPACE* COLON SPACE* value NEWLINE key => ALPHANUMERIC+ (DOT ALPHANUMERIC+)* value => CHARACTER* Example Following is an example of a list of measures encoded as the textual format here specified. 13

14 # This is a comment and it will be ignored by the location server. # Please note that each measure must be terminated by an emtpy line. type: measure.proximity ts: ns: ns: src: crs: WGS84 lat: 45.1 var: 3.1 type: measure.geometric ts: src: long: 9.1 nbl: 15:0.8 type: measure.symbolic ts: src: lat: 45.0 var: 3.0 nbl: 15:0.8 type: measure.hybrid ts: src: long: Context server users guide The context server is the component responsible to collect context data from heterogeneous sources, optionally apply inference rules to derive new context data and finally make available all the collected context infromation to external applications. 4.1 Description At the basis of the context server there is a context model, that specifies which entities and properties are relevant from an application point of view. The context model is based on the abstraction of item, entity and relationship: an entity represent a physical world entity for which we require the context server to collect context information; context items are data values that represents the values of the contextual properties of interest for applications; relationships bind entities to context items or other entities and represents the contextual properties managed by the server. The context model should be defined in terms of a set of classes, implementing the it.cefriel.context.contextentity, it.cefriel.context.contextitem and it.cefriel.context.contextrelationship interfaces. A base context model is included in the framework under the it.cefriel.context.model package. You can extend it by declaring new context sources. 14

15 The context server exposes an API that can be used by external application to send and query for context information about entities. The API is implemented in the context-api module and JAR. Applications should import the API Jar, specify the network address of the context server to connect to and start to send context data; they can also use the API to query for context data, or to register listeners which are notified when an update in the context of an entity occurs. For more information about the API please refer to the Javadoc documentation. 4.2 Deployment and configuration The context server binary package includes all the files needed to run a context server on your machine. Simply extract the content of the binary package to a path of your choice and launch the server using the run script in the /bin folder: run.bat You can stop the server by simply terminating the program (under Windows, select his window and press CTRL-C). Context data collected by the server is persistent and it is stored under the /data folder. This data is recovered when you restart the server. In order to delete it, simply run the clear script located under the /bin folder: clear.bat 4.3 Defining inference rules The context server supports the definition of inference rules that can derive new context information starting from collected context data. These rules are executed by the rule engine Drools and are located under the /rules folder. We refer the reader to the Drools documentation for more information about the syntax of rules. Please note that a rule condition and body consists of simple Java code which has access to a contextservice predefined variable that provides access to the context API in order for rules to query and manipulate context information. Following is an example of rules (included in the binary package): 15

16 <rule name="activity_1" salience="10" no-loop="true"> <parameter identifier="user"> <class>user</class> </parameter> <java:condition>!user.getcontext().getrelateditems(usertophysicalobject.class).isempty() </java:condition> <java:consequence> log.info("rule FIRED: user " + user + " is working."); contextservice.updatecontext(user, new UserToActivity(), new Activity("not working")); </java:consequence> </rule> <rule name="activity_2" salience="10" no-loop="true"> <parameter identifier="user"> <class>user</class> </parameter> <java:condition> user.getcontext().getrelateditems(usertophysicalobject.class).isempty() </java:condition> <java:consequence> log.info("rule FIRED: user " + user + " is not working."); contextservice.updatecontext(user, new UserToActivity(), new Activity("not working")); </java:consequence> </rule> 5 Adaptation framework users guide The adaptation framework is the component of the SAF framewor supporting the adaptation to context of regular Web applications, according to a rule based approach. 5.1 Description The adaptation framework binary packages includes two libraries: WEB-ECA is the adaptation library; Pusher is a utility library providing the push functionality, that is the capability for a web server to push pages to browser (instead of waiting for a browser to request them). In order to use these libraries you simply have to place all the JAR files included in the adaptation framework binary package on your Web application /WEB-INF/lib folder. Following we describe the two libraries in more details. 5.2 Adaptation library The WEB-ECA adaptation library is based on the notion of lever. A lever represents a possible means to influence the behaviour and presentation of a Web application. The framework takes care of assigning 16

17 the values of these levers according to an Event-Condition-Action rule-based approach. The Web application then needs to react on changes of these levers and adapts its presentation, by means of the so-called application managers. The definition of the levers and of the associated application managers is carried out using the web-eca.xml configuration file. Here we report a template of this file with comments that provide instructions on its writing. <?xml version="1.0" encoding="utf-8"?> WEB ECA framework configuration <web-eca xmlns=" xmlns:xi=" xmlns:xsi=" xsi:schemalocation=" web-eca.xsd"> Component definition. This sections defines the component used by the framework, that is the rule manager (you can use the pre-configured BeanRuleManager); the application manager (currently we use the HarmoniaManager, an application manager designed for the Harmonia CMS system) and the pusher manager (you can leave the pre-configured PusherManager) <components> <rulemanager name="rule_manager" class="it.cefriel.webeca.beanrules.beanrulemanager"> <property name="rulebase"> WEB-INF/web-eca.beanrules.xml </property> </rulemanager> <applicationmanager name="harmonia_manager" class="it.cefriel.webeca.harmonia.harmoniamanager"> <property name="prop1">value1</property> </applicationmanager> <pushmanager name="push_manager" class="it.cefriel.webeca.pusher.pushermanager"> </pushmanager> </components> Lever definition. This section defines the adaptation levers. Each lever is identified by a name, a type (by means of a Java class) and whether its value should be persistent or cause a page refresh when updated. Levers can be nested to form a parent-child hierarchy. A child lever contains a derivation element that specifies how to derive the lever value starting from the parent lever value. Note that for each leaf lever a responsible application handler should be designed using the handler element. The following levers are specific to the Harmonia CMS platform. You can override or add new levers provided you provide appropriate application managers that handle their values. <levers> <lever name="presentation" class="java.lang.string" immediate="false" persistent="false"> 17

18 <lever name="webcss" class="java.lang.string" immediate="false" persistent="false"> <derivation> <script language="java"> <![CDATA[ if ("A".equals(presentation)) return "blue.css"; if ("B".equals(presentation)) return "orange.css"; return "default.css"; ]]> </script> </derivation> <handler name="harmonia_manager" /> </lever> <lever name="handheldcss" class="java.lang.string" immediate="false" persistent="false"> <derivation> <choice> <when parent="a" value="blue.css" /> <when parent="b" value="arancio.css" /> <default value="default.css" /> </choice> </derivation> <handler name="harmonia_manager" /> </lever> <lever name="printcss" class="java.lang.string" immediate="false" persistent="false"> <handler name="harmonia_manager" /> </lever> <lever name="fontfamily" class="java.lang.string" immediate="false" persistent="false"> <handler name="harmonia_manager" /> </lever> <lever name="fontsize" class="int" immediate="false" persistent="false"> <handler name="harmonia_manager" /> </lever> </lever> <lever name="content" class="java.lang.string" immediate="true" persistent="false"> <handler name="harmonia_manager" /> </lever> <lever name="layout" class="int" immediate="false" persistent="false"> <handler name="harmonia_manager" /> </lever> 18

19 <lever name="liquid" class="boolean" immediate="false" persistent="false"> <handler name="harmonia_manager" /> </lever> <lever name="simplified" class="boolean" immediate="false" persistent="false"> <handler name="harmonia_manager" /> </lever> </levers> </web-eca> As said, levers are assigned using an ECA rule-based approach. The framework listens for events and updates on beans stored in the application, session and request scopes. These events (E) can cause one or more rules to be evaluated and, if optional conditions (C) are satisfied, an action (A) is performed that consists in the assignment of one or more levers. ECA rules are defined in a specific web-eca.beanrules.xml file. Here we report an example of this file, providing also instructions about its editing. Note that both this file and the web-eca.xml file should be placed under the /WEB-INF folder of your Web application. <?xml version="1.0" encoding="iso "?> Adaptation rules <beanrules xmlns=" xmlns:xi=" xmlns:xsi=" defaultlanguage="java"> Imported packages This section declares all the Java packages that should be imported and made available to Java code inside rules. <import package="it.cefriel.util" /> <import package="java.util" /> <import package="java.lang" /> <import package="it.cefriel.context.model" /> This rule update the page when the contextchanges event on a User bean is intercepted. The behaviour is the following: the rules applies to every session that has a bean of type User called "user". The framework register a listener for the event set "context" (i.e. it uses the addcontextlistener method) and react to the invocation of the contextchanged method on this listener. When this method is invoked, the framework will update the page because the attribute immediate is set to true. This rule applies to every page in the site (the url pattern is a double asterisk, which means every path) <rule name="page refresh on context change" urlpattern="**" priority="100" immediate="true"> <bean identifier="myuser" class="user" name="user" scope="session"> </bean> 19

20 <event identifier="e" sourcebean="myuser" eventset="context" listenermethod="contextchanged"> </event> </rule> This rule update the webcss lever when the user enters a location with code less than 1000 (we assume that such locations corresponds to outdoor locations that need an high-contrast yellow-on-black look&feel). Note the condition, that says "react only when the following condition holds" and the action element, which says "if the rule applies, the assign to this lever the value computed by the script nested in the action element. <rule name="high contrast" urlpattern="**" priority="150" immediate="true"> <bean identifier="myuser" class="user" name="user" scope="session"> </bean> <condition name="condition1"> <script language="java"> <![CDATA[ processingrequest && myuser.getexactlocation()!=null && myuser.getexactlocation().getcode()<1000 ]]> </script> </condition> <action lever="webcss"> <script>"yellow-onblack.css"</script> </action> </rule> </beanrules> 5.3 Push library The push library allows a Web server to push a certain page to the browser. This means that it is not the user to choose the page to visit but the server. The push mechanism is used by the WEB-ECA adaptation library and it is quite cumbersome to implement on HTTP. Therefore, several push methods are provided by the pusher library and the push.xml configuration file allows users to decide which methods should be used according also to the particular user agent used by the client (this because mobile browsers may require particularly simple push methods due to their reduced capabilities). Following we report an example of the push file. You are not required to edit it (unless you want to implement your own push method or to change the configuration). However, you have to place this file under the /WEB-INF/classes folder in order for the framework to read it. <?xml version="1.0" encoding="utf-8"?> Push framework configuration <push xmlns=" xmlns:xsi=" 20

21 <method name="polling" class="it.cefriel.pusher.methods.polling.pollingmethod"> <property name="pollinterval">3000</property> </method> <method name="framepolling" class="it.cefriel.pusher.methods.framepolling.framepollingmethod <property name="pollinterval">3000</property> <property name="title">context-aware application</property> </method> <browser name="msie" useragent="*msie*" method="framepolling"/> <browser name="firefox" useragent="*mozilla*" method="framepolling"/> </push> 6 RFID driver users guide The RFID driver is a standalone Java applications running on a Pocket PC device that connects to a portable RFID reader and sends a stream of proximity measures (i.e. the list of tags detected by the RFID reader) to a remote location server. The RFID driver here described is the Java version of the driver. As part of SAF we provide also a.net version of both the GPS and RFID drivers. We suggest the use of the.net version of the drivers because they are more stable and, most of all, they do not require the installation of a portable JVM on the device. If you still prefer to use this Java driver, you have to copy the content of the binary package on a folder of portable device and ensure you have installed a portable JVM, such as the J9 JVM by IBM. Then edit the driver.conf file and set the address and the port of the location server. Finally launch the driver using the driver.bat script (use a console to launch the driver). 7 GPS driver users guide The GPS driver is a standalone Java applications running on a Pocket PC device that connects to a portable GPS receiver and sends a stream of geometric measures (latitude, longitude) to a remote location server. The GPS driver here described is the Java version of the driver. As part of SAF we provide also a.net version of both the GPS and RFID drivers. We suggest the use of the.net version of the drivers because they are more stable and, most of all, they do not require the installation of a portable JVM on the device. If you still prefer to use this Java driver, you have to copy the content of the binary package on a folder of portable device and ensure you have installed a portable JVM, such as the J9 JVM by IBM. Then edit the driver.conf file and set the address and the port of the location server. Finally launch the driver using the driver.bat script (use a console to launch the driver). 8 Developers Guide SAF is developed using MAVEN ( You need a basic understanding of MAVEN in order to compile the code and generate the documentation. 8.1 MAVEN instructions In the following we gave a brief overview of the main commands to work with the source package. All the instructions refer to Windows: while it should be possible to develop and compile the code under Linux, 21

22 we never tested it so we cannot guarantee that it works out of the box Installing the package and prepare the built environment Unzip the package where you prefer on your file system. Open a command prompt and enter the following command: mvn -v This should display the version of MAVEN currently installed. Please check have at least MAVEN 2.0.8, otherwise please update your installation. It would be also helpful to allocate more memory to MAVEN for its execution: to this end, define the following environment variable (go under control panel system): MAVEN_OPTS = -Xms128m -Xmx256m Now you should be ready to compile the code Compile the code From the command line, move to the root directory of the source package and execute the following command: mvn package -Dmaven.test.skip This tells MAVEN to compile the code and generate the resulting JARs. If everything works you should see a BUILD SUCCESSFUL message at the end Generate the documentation Launch the following two commands from the prompt: mvn install -Dmaven.test.skip mvn site -Dmaven.test.skip mvn site:deploy The first deploys the generated JAR files to the local MAVEN repository (this is required by the site phase). The second generates the HTML documentation from the APT sources (a MAVEN format, used to write these pages) and generates also all the configured MAVEN reports (including Javadocs). The third deploys the generated documentation under the /docs folder under the package (you can change the pom.xml to deploy to a different location / Web site). In order to generate the PDF manual, the Doxia MAVEN plugin has been configured to translate part of the documentation into Latex. You need to create the site, then manually enter folder /target/doxia/latex/manual, open manual.tex, change the document type from book to article (remove also the /chapter instruction) and then compile the document using Latex Generate the source and binary packages From the command prompt, execute the following: mvn assembly:assembly -Dmaven.test.skip MAVEN will generate two zip files for the source and the binary packages, under the /target folder. These files are exactly the packages published on the web site. Please update the assembly.xml descriptors under /src/main/assemblies subfolders if you wish to customize the generated packages. 22

23 8.2 Note on local MAVEN repository This package includes a local MAVEN repository (/mvnrepo)containing JAR files for the Java JTA library, the Pushlet, the RXTX serial port Java driver and for the Prevayler persistence library; these packages were not available on public MAVEN repositories at the time SAF packages were built. 23