Siena - SXML

SXML is a tool that automates the use of XML data within the Siena publish/subscribe service.

If you are a Siena user, or even if you are just evaluating or studying Siena, please consider registering with us by submitting a Siena User Registration Form.

This page covers the following subjects:

License and Credits

SXML is free software. you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

SXML is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

SXML uses the Xerces and Xalan libraries from the Apache Software Foundation. Xalan and Xerces are covered by the Apache Software License. SXML v.2 also uses the Antlr library.

Authors

SXML v.1 is authored primarily by Antonio Carzaniga. An initial prototype was developed by Brian Temple, Jason Brant, and Matthias Hauswirth. SXML v.2 is authored by Chris Corliss.

Feedback

Any sort of feedback is much appreciated. Bug reports and/or technical questions should be directed to Antonio Carzaniga ([email protected]).

Acknowledgments

This work was supported in part by the Air Force Materiel Command, Rome Laboratory, and the Defense Advanced Research Projects Agency under Contract Numbers F30602-94-C-0253, F30602-97-2-0021, F30602-98-2-0163, F30602-99-C-0174, F30602-00-2-0608, and N66001-00-8945; by the Air Force Office of Scientific Research, Air Force Materiel Command, USAF, under grant number F49620-98-1-0061; and by the National Science Foundation under Grant Number CCR-9701973. The content of the information does not necessarily reflect the position or the policy of the US Government and no official endorsement should be inferred.

Overview

SXML creates Siena notifications by mapping elements and attributes of an XML document into attributes of a Siena notification. The mapping is defined through an EventMap object. SXML can also attach the XML source data to the Siena notification it produces, so that subscribers can later extract the XML source from notifications.

SXML uses XPath expressions to select data of interest from the XML document. Since an XPath expression may select multiple nodes (elements and attributes) of an XML document, an SXML mapping also defines the encoding method for multiple selections. This is an example of a SXML mapping:

Siena attribute		XPath	Multivalue specification
string	name	/person/@name	first
int	age	/person/@age	first
string	father	/person/links[relation=father]/person/@name	first
string	mother	/person/links[relation=mother]/person/@name	first
float	salary	/person/job/@salary	last
string	jobs	/person/job/@company	separator ", "
string	education	/person/education	xml

An XPath expression may select more than one element within an XML document, therefore SXML allows to specify a method for synthetizing a Siena attribute value from multiple XML nodes.

Examples

Simple publisher of XML data

XMLPublisher.java:


import siena.*;
import siena.sxml.*;

//
// a simple publisher of XML data
//
public class XMLPublisher {
    public static void main(String args[]) {
	if (args.length < 2) {
	    System.err.println("Usage: XMLPublisher <siena-server> <map> [event..]");
	    System.exit(1);
	}
	try {
	    Siena siena = new ThinClient(args[0]);
	    EventMap m = new EventMap();
	    //
	    // reads the set of mapping rules from a file
	    //
	    m.importRules(args[1]);
	    //
	    // configure the SeXML map to attach the XML sources to
	    // the events that it it produces
	    //
	    m.attachXml();
	    if (args.length == 2) {
		//
		// reads the XML source from the standard input
		//
		siena.publish(m.makeNotification(System.in));
	    } else {
		//
		// reads the XML sources from file passed through the
		// command line
		//
		for(int i = 2; i < args.length; ++i) 
		    siena.publish(m.makeNotification(args[i]));
	    }
	} catch (Exception ex) {
	    ex.printStackTrace();
	    System.exit(1);
	}
	System.exit(0);
    }
};

Simple subscriber of XML data

XMLSubscriber.java:


import siena.*;
import siena.sxml.*;
//
// a simple XML subscriber
//
class SimpleXMLSubscriber implements XMLNotifiable {
    //
    // does nothing but printing out the XML events it receives
    //
    public void notifyXml(String xml_event) {
	System.out.println("XML Event:\n" + xml_event);
    }

    //
    // does nothing at all with patterns of XML events
    //
    public void notifyXml(String[] xml_events) {};
}
//
// a simple subscriber
//
class SimpleSubscriber implements siena.Notifiable {
    //
    // extracts and prints the XML content from the Siena
    // notification, if the notification doesn't have any XML source,
    // prints the notification.
    //
    public void notify(Notification n) {
	String s;
	s = EventMap.getXmlText(n);
	if (s == null) s = n.toString();
	System.out.println("Event:\n" + s);
    }
    //
    // does nothing with patterns
    //
    public void notify(Notification[] events) {};
}

public class XMLSubscriber {
    public static void main(String args[]) {

	if (args.length != 1) {
	    System.err.println("Usage: TestXMLNotifiable <siena-server>");
	    System.exit(1);
	}
	try {
	    ThinClient siena = new ThinClient(args[0]);

	    Filter f = new Filter();
	    f.addConstraint("name",Op.ANY,"");

	    XMLNotifiableWrapper wrapper;
	    wrapper = new XMLNotifiableWrapper(new SimpleXMLSubscriber());
	    
	    siena.subscribe(f, wrapper);
	    siena.subscribe(f, new SimpleSubscriber());
	    Thread.sleep(10000);
	    siena.unsubscribe(wrapper);
	    siena.shutdown();
	} catch (Exception ex) {
	    ex.printStackTrace();
	    System.exit(1);
	}
	System.exit(0);
    }
}

XML notification

swrelease.xml:


<!-- this is an example of an XML notification -->
<swrelease date="Nov 17 2001">
  <system name="DVS" version="1.3.1" footprint="52017"
          href="http://www.inf.usi.ch/carzaniga/dvs/">
    <variance platform="linux2+i386"/>
    <variance platform="solaris2+sparc"/>
    <variance platform="solaris2+i386"/>
    <variance platform="osf1+alpha"/>
    <variance platform="win32+i386"/>
  </system>
  <download>
     <site href="http://www.inf.usi.ch/carzaniga/dvs/"/>
     <site href="ftp://127.0.0.1/serl/dvs/software/"/>
  </download>
  <contact name="Antonio Carzaniga"/>
  <changelog>
    <item type="feature">default behavior for the proxy map:
          addresses that are not mapped are used directly. This means
          that by default, every address maps into itself. Previously,
          DVS returned a failed connection.</item>

    <item type="bugfix" bugid="31415">machines with multiple IP
          addresses are now handled correctly by the proxy map. That
          is, DVS maps all the IP addresses corresponding to a
          hostname into the given proxy address.</item>
  </changelog>
</swrelease>

SXML mapping specification

swrelease-map.sxml:


#
# example of a SXML map
#
string date="/swrelease/@date";
string system="/swrelease/system/@name";
string version="/swrelease/system/@version";
int size="/swrelease/system/@footprint";
string platforms="/swrelease/system/variance/@platform" separator ",";
string uri="/swrelease/site/@href" last;
string changelog="/swrelease/changelog/item" xml;

Packages Download

Version 2

sources: sxml-java-2.0.0.tar.gz
binaries: sxml-2.0.0.jar
API documentation: sxml-javadoc-2.0.0.tar.gz (browse on-line)
manual: sxml_manual.ps
tests package: sxml-tests-2.0.0.jar
demonstration package: sxml-demo-2.0.0.jar, and sxml-demo-files-2.0.0.tar.gz

Version 1

sources: sxml-java-1.0.2.tar.gz (this package includes xalan.jar, xerces.jar, and siena.jar)
binaries: sxml-1.0.2.jar. You also need xalan.jar, xerces.jar, and siena.jar.
documentation: sxml-javadoc-1.0.2.tar.gz (browse on-line)

xalan.jar and xerces.jar are distributed under the terms of the Apache Software License. Every other package is covered by the GNU General Public License. Downloading any combination of source and/or binary packages indicates that you agree to abide by their respective licenses.