User documentation

This document describes the installation and testing of the WS4D Java/Axis?2 DPWS stack on an Apache Tomcat server. After reading this document you will be able to design a device and provide its hosted services using the WS4D Java/Axis?2 DPWS stack.

1. Prerequisites

The Java/Axis?2 DPWS stack has been tested on Java JDK 1.5.0_16, Tomcat 5.5.27 and Apache Axis2 1.3. This section briefly describes the installation of them, if you haven't done that yet.

Java

  • Install Java JDK 1.5.0_16 ( Download from here)
  • Add the binary installation directory (e.g. C:\Programme\Java\jdk1.5.0_16\bin) to the PATH system variable
  • Set the system/user environment variable JAVA_HOME to the installation directory (e.g. C:\Programme\Java\jdk1.5.0_16)

Installing Tomcat

  • Install Tomcat 5.5.27 ( Download it here)
  • We use following configuration:
    • Directory for binaries: C:\Programme\Apache\Tomcat 5.5
    • HTTP Port: 8080
  • Set the system/user environment variable CATALINA_HOME to the installation directory (e.g. C:\Programme\Apache\Tomcat 5.5)
  • Test the installation using the local Tomcat home URL (e.g.  http://localhost:8080/)

Installing Java Axis2

  • The software is currently working with Java Axis2 v1.3 only ( Download page)
  • Install binaries:
    •  Download the binaries
    • Install the binaries into a directory (we use c:\Programme\Apache\axis2-1.3)
    • Set system/user environment variable AXIS2_HOME to your Axis2 binary directory C:\Programme\Apache\axis2-1.3
  • Install Web archive to be deployed with Tomcat

2. Installing the Java/Axis?2 DPWS stack

Installing the SOAP-over-UDP module

  • Download the soapudp-*.mar either directly or as part of the Eclipse project from the download page
  • Download the soapudp-*.jar either directly or as part of the Eclipse project from the download page
  • Copy the file soapudp-*.mar to CATALINA_HOME\webapps\axis2\WEB-INF\modules\ folder
  • Copy the file soapudp-*.jar to CATALINA_HOME\webapps\axis2\WEB-INF\lib\ folder (this extra step will be removed in the upcoming version 0.5)
  • Add following configuration information to the axis2.xml in the directory CATALINA_HOME\webapps\axis2\WEB-INF\conf\
    <!--  soapudp --> 
    <module ref="soapudp" /> 
    <transportReceiver name="mc170" class="org.ws4d.axis2.soapudp.UDPTransportReceiver">
    <parameter name="port">3702</parameter> 
    <parameter name="group">239.255.255.250</parameter> 
    <parameter name="host">YOUR.HOST.IP.ADDRESS</parameter> 
    </transportReceiver>
    <transportReceiver name="soapudp" class="org.ws4d.axis2.soapudp.UDPTransportReceiver">
    <parameter name="port">7500</parameter> 
    <parameter name="host">YOUR.HOST.IP.ADDRESS</parameter> 
    </transportReceiver>
    <transportSender name="soapudp" class="org.ws4d.axis2.soapudp.UDPTransportSender" /> 
    
  • Change YOUR.HOST.IP.ADDRESS to your own host IP address

Explanation of the configuration parameters:

The module configuration contains four elements (tags) for: the SOAP-over-UDP module, UDP multicast receiver, UDP unicast receiver and the UDP sender.

  • SOAP-over-UDP module configuration contains the name of the module.
  • UDP multicast receiver:
    • name: identifies the receiver
    • class: is the Java class of the receiver which will process all messages being sent to the corresponding port, group and IP address
    • port: assigns the receiver for the UDP multicast port
    • group: assigns the receiver for the UDP multicast group IP address
    • host: assigns the host IP for the UDP multicast receiver
  • UDP unicast receiver is similar to the multicast receiver, except the multicast group is not assigned
  • UDP unicast sender:
    • name: identifies the sender. If sender and receiver share the same name, messages will be sent over the port and address defined in the corresponding receiver.

Installing the discovery module

  • Download the discovery-*.mar either directly or as part of the Eclipse project from the download page
  • Copy the file discovery-*.mar to CATALINA_HOME\webapps\axis2\WEB-INF\modules\ folder
  • Add following configuration information to the axis2.xml in the directory CATALINA_HOME\webapps\axis2\WEB-INF\conf\
    <!--  discovery --> 
    <listener class="org.ws4d.axis2.disco.DiscoveryObserver" /> 
    <module ref="discovery" />
    

Explanation of the configuration parameters:

The configuration includes a listener for discovery messages (listener element) and a reference to the discovery module (module element).

Installing the MetadataTransfer module

  • Download the metadatatransfer-*.mar either directly or as part of the Eclipse project from the download page
  • Copy the file metadatatransfer-*.mar to CATALINA_HOME\webapps\axis2\WEB-INF\modules\ folder
  • Add following configuration information to the axis2.xml in the directory CATALINA_HOME\webapps\axis2\WEB-INF\conf\
    <!-- metadatatransfer -->
    <listener class="org.ws4d.axis2.mtf.MetadataTransferObserver" />
    <module ref="metadatatransfer" />
    

Explanation of the configuration parameters:

The configuration includes a listener for metadata transfer messages (listener element) and a reference to the discovery module (module element).

Testing the installed modules

  • Test the installation of Axis2 using the local_Tomcat_home_URL/axis2/axis2-admin/listModules (in our case  http://localhost:8080/axis2/axis2-admin/listModules). You may have to login to the admin pages.
  • Check if the page is shown and the Java/Axis?2 DPWS modules (discovery, soapudp and metadatatransfer) are displayed

CONGRATULATIONS: The Java/Axis?2 DPWS stack is installed. In the next section, we will test the functionality of the stack using the DPWS Explorer and an example device.

3. Testing the Java/Axis?2 DPWS stack

In this section, we will design a sample device, which uses the version service of Axis2 as a hosted service.

  • Create a new directory (e.g. sampledevice) in the directory CATALINA_HOME\webapps\axis2\WEB-INF\services and create another directory (called META-INF) inside of it
  • Place an empty file (called services.xml) into the META-INF directory
  • Instead of putting META-INF and the included services.xml into a directory, you may also pack the META-INF directory into a ZIP-file and rename the file to *.aar
  • Fill the services.xml file with following content:
    <serviceGroup name="sampledevice">
      <service name="sampledevice">
        <parameter name="useOriginalwsdl">false</parameter>
        <parameter name="modifyUserWSDLPortAddress">true</parameter>
      <!-- -->
      <!-- Discovery definitions -->
      <!-- -->
        <parameter name="Discovery" auto="true ">
          <enableAutoDiscovery>true</enableAutoDiscovery>
          <UUID>urn:uuid:A3CE4B9E4585FF5BDF1183465332886</UUID>
          <types>
            <type ns="http://schemas.xmlsoap.org/ws/2006/02/devprof" prefix="wsdp" name="Device" />
            <type ns="http://www.ws4d.org/ws4d-axis2/tutorial" prefix="bs" name="SampleDevice" />
          </types>
          <scopes>
            <scope uri="http://schemas.xmlsoap.org/ws/2005/04/discovery/adhoc" />
            <scope uri="socom:non-public-area2" />
          </scopes>
          <UDPTransportSenders>
            <sender name="soapudp" />
          </UDPTransportSenders>
        </parameter>
      <!-- -->
      <!-- Metadata definitions -->
      <!-- -->
        <parameter name="DPWSDevice">
          <ThisDevice xmlns:dpws="http://schemas.xmlsoap.org/ws/2006/02/devprof">
            <FriendlyName xml:lang="EN">Sample Device</FriendlyName>
            <FirmwareVersion>alpha</FirmwareVersion>
            <SerialNumber>1</SerialNumber>
          </ThisDevice>
          <ThisModel xmlns:dpws="http://schemas.xmlsoap.org/ws/2006/02/devprof">
            <Manufacturer>WS4D</Manufacturer>
            <ManufacturerUrl>http://www.ws4d.org/</ManufacturerUrl>
            <ModelName>Sample Device</ModelName>
            <ModelNumber>1.0</ModelNumber>
            <ModelUrl>http://www.ws4d.org/</ModelUrl>
            <PresentationUrl>http://www.ws4d.org/</PresentationUrl>
          </ThisModel>
          <Relationship>
            <Host xmlns:dpws="http://schemas.xmlsoap.org/ws/2006/02/devprof">
              <ServiceID>sample-device-id:2</ServiceID>
            </Host>
            <Hosted name="Version" xmlns:dpws="http://schemas.xmlsoap.org/ws/2006/02/devprof">
              <EndpointReference>http://localhost:8080/axis2/services/Version</EndpointReference>
              <Types>
                <Type xmlns:ac="http://www.ws4d.org/ws4d-axis2/tutorial/SampleDevice">ac:SampleDeviceService</Type>
              </Types>
              <ServiceID>http://ws4d.tutorialdevice.org/SampleDeviceService1</ServiceID>
            </Hosted>
          </Relationship>
        </parameter>
      </service>
    </serviceGroup>
    
  • In our example the only hosted service is the Version service which comes with Axis2
  • To test the DPWS device, please  download the DPWS Explorer 2
  • Start Tomcat and search for devices using the DPWS Explorer
  • Congratulations you will see now all message exchanges with the Java/Axis?2 DPWS stack
  • Now, you can design your own devices by adapting the sample device. If you change the Hosted section according to your own services, you will be able to find them using the Java/Axis?2 DPWS stack. That means you do not have to change your existing services. You may also include the Axis2 service description beneath the description of the device.

Explanation of the configuration parameters:

  • The first two parameters are standard parameters from Axis2. It is important to note that a device does not have an original WSDL. If you change that parameter you will not receive a WSDL description from the device.
  • Discovery parameters:
    • Discovery: identifies discovery related parameters (do not change the identifier).
    • enableAutoDiscovery: switches on the automatic transmission of Hello and Bye messages
    • UDPTransportSender: you must use a sender which is also defined in the axis2.xml configuration file
    • All other parameter are DPWS specific and self-describing, please refer to the  DPWS specification for explanation.
  • MetadataTransfer? parameters
    • DPWSDevice: identifies MetadataTransfer? related parameters (do not change the identifier)
    • All other parameter are DPWS specific and self-describing, please refer to the  DPWS specification for explanation.

4. Switching on the logging of debug message and errors

  • Add the following code to the log4j.properties in the directory CATALINA_HOME\webapps\axis2\WEB-INF\classes\
    log4j.logger.httpclient=DEBUG, AXIS2
    log4j.logger.org.apache=ERROR, AXIS2
    log4j.logger.org.ws4d.axis2.soapudp=DEBUG, SOAPUDP
    log4j.logger.org.ws4d.axis2.disco=DEBUG, DISCO
    log4j.logger.org.ws4d.axis2.mtf=DEBUG, MTF
    
    log4j.appender.AXIS2=org.apache.log4j.RollingFileAppender
    log4j.appender.AXIS2.File=log/axis2.log
    log4j.appender.AXIS2.MaxFileSize=900KB
    log4j.appender.AXIS2.MaxBackupIndex=9
    log4j.appender.AXIS2.layout=org.apache.log4j.PatternLayout
    log4j.appender.AXIS2.layout.ConversionPattern=%r %p [%t] (%F.%M:%L) - %m%n
    
    log4j.appender.SOAPUDP=org.apache.log4j.RollingFileAppender
    log4j.appender.SOAPUDP.File=log/soapudp.log
    log4j.appender.SOAPUDP.MaxFileSize=200KB
    log4j.appender.SOAPUDP.MaxBackupIndex=5
    log4j.appender.SOAPUDP.layout=org.apache.log4j.PatternLayout
    log4j.appender.SOAPUDP.layout.ConversionPattern=%r %p [%t] (%F.%M:%L) - %m%n
    
    log4j.appender.DISCO=org.apache.log4j.RollingFileAppender
    log4j.appender.DISCO.File=log/disco.log
    log4j.appender.DISCO.MaxFileSize=200KB
    log4j.appender.DISCO.MaxBackupIndex=5
    log4j.appender.DISCO.layout=org.apache.log4j.PatternLayout
    log4j.appender.DISCO.layout.ConversionPattern=%r %p [%t] (%F.%M:%L) - %m%n
    
    log4j.appender.MTF=org.apache.log4j.RollingFileAppender
    log4j.appender.MTF.File=log/metadatatransfer.log
    log4j.appender.MTF.MaxFileSize=200KB
    log4j.appender.MTF.MaxBackupIndex=5
    log4j.appender.MTF.layout=org.apache.log4j.PatternLayout
    log4j.appender.MTF.layout.ConversionPattern=%r %p [%t] (%F.%M:%L) - %m%n
    
  • Adapt the error message level according to your needs (e.g. DEBUG, ERROR) - see the  Apache Log4J homepage for further information
  • All log files will be stored in the directory CATALINA_HOME\log, there are separate files for each module