User's Guide

Building XML Server applications

Communication via Web Server Interface (WSI)

The ST: XML Communications feature extends the Web Server Interface (WSI) layer of Web Connection to support XML and handle the incoming server requests. VisualAge XML support provides the AbtXmlWsiHandler, which is a subclass of AbtWsiHandler. You can subclass the AbtXmlWsiHandler to create custom XML request handlers. You must then override the abtWsiHandleWsiTransaction: method in order to handle incoming XML requests.

VisualAge Smalltalk provides a new Part type named XML Request Handler, in the New Part view to simplify the creation of AbtXmlWsiHandler subclasses.

VisualAge Smalltalk provides a new transport called xml-tcp that allows applications to process socket requests without first passing them through an HTTP server. To use the xml-tcp server transport, perform the following steps:

  1. Start a WSI Server... window of the WSI monitor
  2. Specify xml-tcp for the Transport.
  3. Specify a handler class name in the Request Handler. The handler class is then responsible for processing socket requests via its abtWsiHandleWsiTransaction: method.

For more information on setting up and using the Web Server Interface, see the VisualAge Smalltalk Web Connection Guide.

XML Server Samples

Creating an XML HTTP request handler using the XML DOM parser

This section steps you through the process of building a sample server application. This application is a simple illustration of a customer request handler that uses an XML DOM parser (AbtSampleCustomerRequestHandler). The main steps to create this sample are as follows:

  1. Create the AbtSampleCustomerRequestHandler as a subclass of the AbtXmlWsiHandler class.
  2. Write a method to handle the customer transaction. The #abtHandleWsiTransaction: sample method does the following:
    1. Obtains the XML string from the transaction object.
    2. Parses the XML string using the DOM parser
    3. Uses the input serialization API to convert the DOM into an AbtXmlSampleCustomerRequest object.
    4. Processes the command specified in the customer request object.
    5. Creates an AbtXmlSampleCustomerResponse object and write its XML representation to the response of the AbtWsiTransaction using the output serialization method #abtXmlPrintString.
    abtHandleWsiTransaction: anAbtWsiTransaction
      " Handle the incoming AbtWsiTransaction.  The expected content is an 
        AbtXmlSampleCustomerRequest passed as XML.  This method performs the following steps.
      1)  Obtain the XML string from the transaction object. 
      2)  Parse the XML string using the DOM parser
      3) Use input serialization API to convert the DOM into an AbtXmlSampleCustomerRequest 
         object  
      4) Process the command specified in the customer request object
      5) Create an AbtXmlSampleCustomerResponse object and write its XML representation 
         to the 'response' of the AbtWsiTransaction using output serialization method 
         #abtXmlPrintString  "
     
      | xmlString customerRequest  domDocument   |
      " Get the XML request string from the passed transaction object "
      xmlString := anAbtWsiTransaction request content.
     
      " Parse the XML string while handling any exceptions that occur during parsing "
      self handleParseExceptionsWhile: [
         domDocument := AbtXmlDOMParser newNonValidatingParser parse: xmlString  ].
     
      " Construct a customerRequest object from the contents of the incoming domDocument.  
      This requires that the contents of the DOM be 'mapped' into the desired object  "
      domDocument notNil
         ifTrue: [customerRequest := self customerFromDOM: domDocument ].
     
      " An error occured converting the DOM into a customer object.  Pass back some XML to 
        report the error "
      customerRequest isNil
        ifTrue: [ anAbtWsiTransaction response content: self createErrorString contentType: 
                  'text/xml' ]
        ifFalse:  [
          anAbtWsiTransaction response content: 
            (self processCustomerRequest: customerRequest ) contentType: 'text/xml' ]
    
  3. Write a method to create a customer object from the DOM. The customerFromDOM: sample method constructs a customer request object from the contents of an incoming DOM. This method requires that the contents of the DOM be mapped into the desired object.

    This method also checks the object cache for a mapping specification. If a mapping specification is not found, a new mapping specification is created from the external mapping file and cached to the object cache.

    customerFromDOM: aDocumentObjectModel
       " Create a new instance of AbtXmlSampleCustomer using the passed DOM "
     
       | mappingDOM mappingSpec object mapFilePath sep |
     
      " Check the object cache for the presence of the mappingSpec.  If it is not found, 
        create a new mappingSpec from  the external mapping file, and add the resulting 
        mappingSpec to the objectCache for future usage "
     
      ( mappingSpec := AbtXmlObjectCache current mappingSpecNamed: self mappingSpecName ) isNil
      ifTrue: [
          sep := AbtXmlResourceReader current pathSeparator asString.
          mapFilePath := '..', sep, 'xml', sep, 'samples', sep, 'customer.map'.
     
          self handleParseExceptionsWhile: [
            mappingDOM := AbtXmlDOMParser newValidatingParser parseURI: mapFilePath ].
     
          self handleDOMExceptionsWhile: [
          mappingSpec := AbtXmlMappingSpec fromMappingDOM: mappingDOM ].
          mappingSpec notNil
              ifTrue: [ mappingSpec addToXmlObjectCache ] ].
     
      mappingSpec notNil
          ifTrue:  [ object := aDocumentObjectModel mapUsing: mappingSpec ].
     
      ^object
    
  4. Write a method to process the customer request. The processCustomerRequest: sample method processed the command described in the incoming customer request.
    processCustomerRequest: anAbtXmlSampleCustomerRequest
      " Process the command described in the passed customer request "
     
      | customerResponse customer |
      anAbtXmlSampleCustomerRequest isNil
         ifTrue: [ ^self createErrorString ].
     
      customerResponse := AbtXmlSampleCustomerResponse new.
    	
      " Simple application code for demonstration purposes "
      anAbtXmlSampleCustomerRequest request = 'INQUIRY'
         ifTrue: [ 
          customerResponse customer: anAbtXmlSampleCustomerRequest customer.
          customerResponse customer lastName = 'Programmer'
            ifTrue: [ 
              customerResponse customer
                 firstName: 'Joe' ;
                 lastName: 'Programmer' ;
                   email: 'joeprogrammer@us.ibm.com' ;
    	             streetAddress: '100 IBM Way' ;
    	           city: 'RTP' ;
                 state: 'NC' ;
                 zip: '27609'.
              customerResponse response: 'Success' ]
            ifFalse: [ customerResponse response: 'Not found' ] ]
          ifFalse: [
           customerResponse response: 'Not supported' ].
     
      ^customerResponse abtXmlPrintString
    
  5. Write a method to handle the DOM exceptions. The handleDOMExceptions sample method handles any exceptions that occur while manipulating DOM objects:
    handleDOMExceptionsWhile: aBlock
      " Execute the passed block wrapped in code to handle exceptions that occur 
        while manipulating DOM objects"
    	
      aBlock
        when: AbtDOMConstants::AbtDOMException
        do: [ :aSignal | 
           self logError: aSignal argument	printString	
           ]
    
  6. Write a method to handle parser exceptions. The handleParseExceptionsWhile method handles SGML exceptions:
    handleParseExceptionsWhile: aBlock
      " Execute the passed block wrapped in code to handle SGML exceptions "
    	
      aBlock
        when: SgmlExceptions::SgmlException
        do: [ :aSignal | 
           self logError: aSignal argument	printString	
            ].
    

Creating an XML HTTP request handler using the SAX parser

This section steps you through the process of building a sample customer request handler that uses a SAX parser.

  1. Create the AbtSampleSaxCustomerRequestWsiHandler as a subclass of the AbtXmlSampleCustomerRequestHandler class. In the VisualAge Organizer, create a new part. For Part type, select XML Request Handler. For Part class, type the name of your new class (ex. AbtXmlSampleSaxCustomerRequestWsiHandler).
  2. Write a method to override the #abtHandleWsiTransaction: method and handle the customer transaction using a SAX parser. The #abtHandleWsiTransaction: sample method does the following:
    1. Obtains the XML string from the transaction object.
    2. Parses the XML string using the SAX parser and custom SAX handler named AbtXmlSamplesSaxCustomerContentHandler.
    3. Processes the command specified in the resulting customer request object.
    4. Creates an AbtXmlSampleCustomerResponse object and write its XML representation to the response of the AbtWsiTransaction using output serialization method #abtXmlPrintString.
    abtHandleWsiTransaction: anAbtWsiTransaction
      " Handle the incoming AbtWsiTransaction.  The expected content is an 
        AbtXmlSampleCustomerRequest
        passed as XML.  This method performs the following steps.
      1)  Obtain the XML string from the transaction object. 
      2)  Parse the XML string using the SAX parser and custom SAX handler named 
          'AbtXmlSamplesSaxCustomerContentHandler'
      3) Process the command specified in the resulting customer request object
      4) Create an AbtXmlSampleCustomerResponse object and write its XML representation 
         to the 'response' of the AbtWsiTransaction using output serialization method 
         #abtXmlPrintString  "
     
      | xmlString customerRequest     |
      " Get the XML request string from the passed transaction object "
      xmlString := anAbtWsiTransaction request content.
     
      " Parse the XML string while handling any exceptions that occur during parsing "
      self handleParseExceptionsWhile: [
        customerRequest := ( AbtXmlSaxParser newNonValidatingParser contentHandler: 
           AbtXmlSampleSaxCustomerContentHandler new )
        parse: xmlString  ].
     
      customerRequest isNil
        ifTrue: [ anAbtWsiTransaction response content: self createErrorString contentType: 
                  'text/xml' ]
        ifFalse:  [
           anAbtWsiTransaction response content: 
             (self processCustomerRequest: customerRequest ) contentType: 'text/xml' ]
    
  3. Create a default handler for the SAX parser. The AbtXmlSampleSaxCustomerContentHandler sample class is a subclass of the AbtXmlSaxDefaultHandler class.
    
    

Application Prerequisites

Before you package an application, make sure that the prerequisites are defined. The following list shows the XML support applications and the features they provide:

AbtXmlDOMParserApp
For applications that parse XML to create a document object model (DOM) object.

AbtXmlSaxParserApp
For applications that parse XML using a SAX parser with customized SAX handlers.

AbtXmlSerializationApp
For applications that use the input and/or output serialization API.

AbtXmlServerInterfaceTcpApp
For applications that use the WSI extensions for XML to perform XML transaction processing.

AbtXmlServerInterfaceViewTcpApp
For applications that use the Web Server Interface Monitor UI to manage WSI connections.


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]