next_inactive up previous


XSoapExt Tutorial for Python Users


Contents

1 Overview

XSoapExt is a fast, lightweight C++ library for SOAP and Web service utilities. High performance and flexibility is the major concern of XSoapExt. Also binary XML and mulitple XML encoding schemas is one of its highlights. This tutorial is mainlly about the usage of its Python extension module.

2 Download

3 Prerequisites

3.1 Required softwares

3.2 Platform notes

4 Install (Note: below instructions are just for prepbuild, the current release has already adopated gnu automake/autoconf )

  1. check out the source code from extreme CVS repository:
      cvs co xct/XSoapExt xct/mslib xct/ldmalloc xct/prepbuild xct/xbs xct/build_xsoap xct/.xct_top_marker
    
  2. configure ,prepbuild and make XSoapExt:
    There are two options to build the XSoapExt:
  3. build the Python extending moduel:
    cd XSoapExt
    cd <platform specific directory> #(e.g. linux-2.6-x86-gcc-3.3.5---32-dyn-dbg)
    
    Suppose you are under the paltform specific directory,(e.g. linux-2.6-x86-gcc-3.3.5--32-dyn-dbg), then
    cd src/pyton
    gmake
    
    Then _xsoap.so and xsoap.py will be generated, now you can run Python, and load xsoap into Python. You can find couple demo .py files in this directory, some of which also will be introduced in the below section. Running those demo files by Python function execfile.

5 XML data model manipulation (XQDM)

The below code is from test_xqdm.py and test_xqdm2.py.

5.1 QName

QName is the basic type in the XQDM;
# create a QName 
n = QName("www.foo.com","foo")

# print a QName
print n.toString()

5.2 Create the new node in the XML data model,

the node can be ElementNode, TextNode, AttributeNode, and NamespaceNode;
# create an element node
e1 = make_Element(QName("www.foo.com","foo"))

# create an element node , which has a text node "hello" 
e2 = make_Element(QName("www.foo.com","foo"), "hello")

# create an attribute node, whose name is age and value is 37
a1 = make_Attribute(QName("","age"),"37")

5.3 Create the XML tree

For example the below code will add attribute node a1 and element node e2 under the element node e1 as its children nodes;
# add attribute node under e1 element
e1.append_attribute(a1)

# add element2 under e1 element
e1.append_child(e2)

5.4 Visit the XML tree or subtree

You can print a tree or subtree, by the code
print elementToString(e1)

Or you can iterate the tree by the interfaces:

# iterate over the all attributres of the element node
i = 0
while i < e1.attributes_size() :
    a3 = e1.attributes(i)
    print a3.node_name().toString() + "=" + a3.string_value()
    i += 1

# iterate over the all children elements of the element node
print "The children elements are: "
i = 0
while i < e1.elements_size() :
    e3 = e1.elements(i)
    print e3.node_name().toString()
    i += 1

# iterate over the all text nodes of the element node
print "The textnode elements are: "
print e.text()
i = 0
while i < e1.textnodes_size() :
    t3 = e1.textnodes(i)
    print t3.string_value()
    i += 1

6 SOAP

Below code is from test_xsoap.py.

6.1 SOAP Message

XSoapExt provides functions to create and visit the SOAP envelope, body and header:
    # assume the content is just a dummy element
    content = make_Element(name)

    # create the SOAP body element
    body = make_Body()

    # add the content element into SOAP body
    body.add_element(content)

    # create the SOAP envelope including the body
    envelope = make_Envelope(body)

    # visit the element associated with the envelope, body or header
    print elementToString(envelope.element())

6.2 SOAP Client

To send a SOAP request and receive its response, a SOAP envelope should be created as shown previously. Then a proxy class DefaultClientEnd, which representing the protocol stack at client side, is created and this object will try to connect the remote SOAP server.
 # Now we create the communication end representing the cliend side.
 # The end is called DefaultSoapClientEnd,
 # it needs url of the server port to be the input parameter
 remoteEnd = DefaultClientEnd("www.foo.com",port,path);
Thereafter by calling DefaultClientEnd.send_request(SoapEnvelope), we can send the SOAP envelope of the request message synchronously; The return value of the method call is the SOAP envelope of the response message, which could be SOAP response message or SOAP fault message.
    # send the SOAP envelope via the client end
    # and synchronously wait the response
    ret = remoteEnd.send_request(envelope);

    # print the response
    print elementToString(ret.element())

6.3 SOAP Server

XSoapExt adopts a similar concept architecture as the one defined in WSDL. In WSDL a Port is a collection of Operations, likewise XSoapExt provides two basic virtual classes, DefaultPort and DefaultOperation, to represent the Port and Operations respectively. To provide application specific functionality, user should derive the two classes, and override some call-back methods.

For example, we are going to build a Math service which will supported two operations: Add and Minus;

The complete code of the Math server and client can be found at .

7 WS-Eventing

XSoapExt implemented the WS-Eventing specification. The eventing module consists of 4 main components: sink, source, subscription manager and subscription. To show how the eventing system works, we are giving a time server demo, in which a server as the eventing source sends the current local time to all of the subscribers who are interested in the time event and a event sink is created as a subscriber for the time eventing.

Below code is from test_eventing_sink.py and test_eventing_source.py.

7.1 Eventing Sink

A event sink is an entity who is listening the any event sent from event sources and then does the application specific action on the event. XSoapExt provides a base virtual class, ThreadSafeEventSink, as the framework of event sink entity. To define a user specific event sink, you need inherit the ThreadSafeEventSink and override the handle_safe_event method, which is a call back (hook) method and will be invoked by the background thread when an event arriving. In the time eventing demo, the sink will be defined as:
# a user specific event sink
# which will listen the time event
# and then print the server time contained in the event.
class TimeEventSink(ThreadSafeEventSink):
    def __init__(self, port, path):
        ThreadSafeEventSink.__init__(self,port, path)
    # override this method to provide user specific processing of the event 
    def handle_safe_event(self,event):
        # assume the schema of received event is
        # <Body><LocalTime>...</></>
        # event argument is the element of the SOAP message body
        if event.elements_size() != 1:
            print "the event format is incorrect"
        print "The the server time is " + event.elements(0).text()
The event argument in the handle_safe_event actually is the element in the body of the received SOAP message. This simple sink just extracts the time data from the message and prints it
To create and launch the sink, what you need to do is just create an instance of the sink type:
# now you can launch the sink 
s = TimeEventSink(sinkPort, sinkPath)

7.2 Subscription Request

After you create the event sink, you can build a subscription to subscribe the event sink to an event source for a specific topic; XSoapExt provides a default subscription class to Python user.
sub = DefaultSubscription(topic,sourceURI,sinkURI)
sub.subscribe();
As the code shows, to create the subscription you need to specify the event topic, the location of the event sink and the location of the event source. That means the event sink, event source and the host where the subscription is issued can be different hosts in the networking. ``sub.subscribe()'' will send the subscription request and wait the response from the event source.

7.3 Event Source and Subscription Manager

According the WS-eventing specification, event source and subscription manager are two separated services (and may be different hosts). Event source delivers the event to the subscribers, while subscription manager is responsible for the subscription renew, canceling and other management stuff. But in most cases the two services coexist in a same application space. So in the sake of convenience for Python users, XSoapExt provides a super service class, called AllInOneEventSource, in which both a default subscription manager service and default event source service are defined. When an instance of this class is created, two of the services will be created and launched automatically. The below code shows how to create the instance:
# create and launch the event source and subscription manager
# in this example, we use a simple  all in one implemenation, which
# includes the both event source and subscription manager and
# and it accepts all subscribing request 
source = AllInOneEventSource(sourcePort,sourcePath,managerPort,managerPath);
To create the object, you need to specify the port and path for both event source service and subscription manager service; Thereafter, you can send the event to the subscriber of the event source by calling source.notify(topic,message), which will send the message to all the subscriber who are interested in the topic. The below code shows in the time eventing demo how to generate an XML element including current time and send it to all subscribers through the event source.
    e = make_Element(QName("","LocalTime"), time.asctime())
    source.notify(topic,e);

It should be noted that the convenience is at the cost of policy flexibility. Event resource and subscription manager could have user specific management policy, like whether a subscription request is allowed, whether a renew request is allowed as so on. But AllInOneEventSource adopts simplest policies, by which all the requests will be allowed.

About this document ...

XSoapExt Tutorial for Python Users

This document was generated using the LaTeX2HTML translator Version 2002-2-1 (1.71)

Copyright © 1993, 1994, 1995, 1996, Nikos Drakos, Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The command line arguments were:
latex2html -split 0 -show_section_number python_tutorial.tex -dir /u/welu/work/doc/docs/web/portals/XSoapExt/python_tutorial/

The translation was initiated by Wei Lu on 2005-05-24


next_inactive up previous
Wei Lu 2005-05-24