WebServices mit Java, Axis, XDoclet und Eclipse

Außer der Laufzeit-Bibliothek muss man bei praktisch jedem Projekt andere Bibliotheken mit einbinden. Da diese bei jedem Entwickler auf unterschiedlichen Pfaden installiert sein können, benutzt man sogenannte Classpath-Variablen.

Im Projekt werden so nur symbolische Namen gespeichert, die jeder Entwickler auf seine lokale Installation anpassen kann. Braucht man z.B. „servlet.jar“ von Tomcat, dann wird sie im Projekt als „TOMCAT_HOME/common/lib/servlet.jar“ referenziert. Wo Tomcat dann genau installiert ist, wird vom Entwickler selbst festgelegt in dem er den Wert von TOMCAT_HOME entsprechend seiner lokalen Installation einstellt.

Wenn man in einem Team entwickelt und relativ neue Technologien im Einsatz hat, dann ändern sich Versionen der zugehörigen Bibliotheken sehr schnell. Damit nicht das heillose Chaos ausbricht und seltsame Effekte auftreten, die auch noch von einem zum anderen Teammitglied unterschiedlich ausfallen, ist es sehr wichtig, dass alle immer die gleichen Versionen alle Komponenten verwenden.

Deshalb empfehle ich immer Namen für Bibliotheken zu verwenden, die schon im Namen die Versionsnummer enthalten. z.B. „castor-0.4.1.jar“. Wenn alle Bibliotheken auch so im Projekt referenziert werden, ist sichergestellt, dass alle das Gleiche verwenden.

Man kann die eingebaute Dokumentation sehr leicht erweitern mit eigenen Texten erweitern. Zum einen lassen sich alle mit JavaDoc erzeugten API-Dokumentationen direkt einbinden. Das gilt zu allererst natürlich für das Java-SDK selbst, aber dann natürlich auch für alle im Projekt benutzten Bibliotheken.

Zum anderen können Plugins ihre Dokumentation nahtlos integrieren, als Beispiel gibt's im Download-Bereich diesen Artikel auf als Plugin, wo durch er eben in der Eclipse Hilfe erscheint.

Um die Möglichkeiten voll auszunutzen, sollte man zu jeder verwendeten Bibliothek (JAR-File) die entsprechende API-Dokumentation, sowie den Sourcecode (soweit verfügbar) zuordnen. Wenn man ein komplettes JDK installiert inklusive Source erkennt Eclipse das automatisch. Für alle individuellen Bibliotheken ordnet man über die Properties eines jeden JARs (erreichbar über das Kontextmenü) die Dokumentation und das Source-Archiv zu.

Entsprechend wird auch die API-Dokumentation des eigenen Projekts mit eingebunden:

So vorbereitet liefert den Druck auf Shift-F2 jederzeit die Dokumentation zum Objekt unter dem Cursor, genauso wie F3 das betreffende Sourcefile öffnet.

Wenn man ein Project neu anlegt ist fortan Tomcat-Projekt neben Java-Projekt als neuer Projekttyp verwendbar. Ein bestehendes Projekt läßt unter „Projekt-Properties“ zum „Tomcat-Projekt“ machen:

Wenn alles so vorbereitet ist, dann ist im Kontextmenü des Projekts ein zusätzlicher Eintrag vorhanden:

Zunächst wird das ZIP-Archiv in die Verzeichnishierarchie von Eclipse entpackt. Nach dem Neustart von Eclipse läßt sich das Plugin unter „Windows / Preferences“ konfigurieren:

Zunächst gibt man den Pfad zur tools.jar vor. Das ist die Bibliothek aus dem JDK welche den Compiler enthält. Falls man mehrere JDKs installiert hat, sollte man darauf achten, dass der Compiler des JDKs verwendet wird, welches auch für das Projekt eingestellt ist.

Dann wählt man die passenden Parameter für die Tomcat-Installation.

Die Einstellungen des JSP-Editor sind eher kosmetischer Natur und sollen hier nicht weiter erwähnt werden.

Damit die verschiedenen Views und Actions sichtbar werden, muss man in der Java-Perspective über „Customize Perspective“ (genau wie oben beim Tomcat-Plugin) einige der Lomboz-Optionen aktivieren:

Entsprechend werden im Zweig „Windows / Show View“ der „Lomboz J2EE View“ aktiviert und im Zweig „Other“ die „Lomboz Actions“.

Neben den Wizards zur Erstellung neuer Resourcen, kommt in der Taskleiste damit ein neuer Button „J2EE Project Builder“ hinzu.

Im beigefügten Beispiel-Projekt ist ein primitiver WebService realisiert:

/**
 * @author sr
 * @axis.service name="MyTestService" scope="Request" enable-remote-admin="true"
 * @axis.useHandler name="track"
 */
public class TestService {

    /**
     * calcs a sum.
     * @axis.method
     * @param p1 first parameter
     * @param p2 second parameter
     * @return the sum of both parameters
     */
    public int sum( int p1, int p2 ) {
        return p1+p2;
    }
    
    /**
     * gets the address
     * @axis.method
     * @param id
     * @return the address
     */
    public String getAddress( int id){
        return null; 
    }

}

Im Beispiel-Projekt ist ein spezielles Template für XDoclet enthalten, welches einen Deployment-Descriptor für Axis erzeugt. Es wertet die im Kapitel 10 beschriebenen Tags aus und erzeugt so ein „deploy.wsdd“ File.

<?xml version="1.0" encoding="utf-8"?>

<deployment
 xmlns="http://xml.apache.org/axis/wsdd/"
 xmlns:java="http://xml.apache.org/axis/wsdd/providers/java"
 xmlns:xsi="http://www.w3.org/2000/10/XMLSchema-instance">

<XDtClass:forAllClasses>

<!-- ... check for Handlers -->

</XDtClass:forAllClasses>

<XDtClass:forAllClasses>

<XDtClass:ifHasClassTag tagName="axis.service" paramName="name">

 <service name="<XDtClass:classTagValue tagName="axis.service" paramName="name"/>"

<!-- ... -->

     <XDtClass:ifDoesntHaveClassTag tagName="axis.service" paramName="provider">
       <XDtType:ifIsOfType type="javax.ejb.EntityBean,javax.ejb.SessionBean">
       provider="java:EJB"
       </XDtType:ifIsOfType>
       <XDtType:ifIsNotOfType type="javax.ejb.EntityBean,javax.ejb.SessionBean">
       provider="java:RPC"
       </XDtType:ifIsNotOfType>
       >
     </XDtClass:ifDoesntHaveClassTag>

     <XDtClass:ifHasClassTag tagName="axis.useHandler" paramName="name">
     <requestFlow>
         <handler type="<XDtClass:classTagValue tagName="axis.useHandler" paramName="name"/>"/>
     </requestFlow>
     </XDtClass:ifHasClassTag>

     <parameter name="className" value="<XDtClass:fullClassName/>" />

    <!-- check if remoteAdmin param is present -->
     <XDtClass:ifHasClassTag tagName="axis.service" paramName="enable-remote-admin">
       <parameter name="enableRemoteAdmin" value="<XDtClass:classTagValue tagName="axis.service" paramName="enable-remote-admin"/>" />
     </XDtClass:ifHasClassTag>

     <parameter name="allowedMethods"

     <XDtClass:ifDoesntHaveClassTag tagName="axis.service" paramName="include-all">
       <XDtEjbSession:ifStatelessSession>
                value="create"
       </XDtEjbSession:ifStatelessSession>

       <XdtEjbSession:ifStatefulSession>
                value="<XDtMethod:forAllMethods><XDtEjbHome:ifIsCreateMethod><XDtMethod:methodName/> </XdtEjbHome:ifIsCreateMethod></XDtMethod:forAllMethods>"
       </XDtEjbSession:ifStatefulSession>

       <XDtType:ifIsNotOfType type="javax.ejb.SessionBean">
                value="<XDtMethod:forAllMethods><XDtMethod:ifHasMethodTag tagName="axis.method"><XDtMethod:methodName/>
 </XDtMethod:ifHasMethodTag></XDtMethod:forAllMethods>"
       </XDtType:ifIsNotOfType>

     </XDtClass:ifDoesntHaveClassTag>

     <XDtClass:ifHasClassTag tagName="axis.service" paramName="include-all">
                value="*"
     </XDtClass:ifHasClassTag>
     />

     <parameter name="scope" value="<XDtClass:classTagValue tagName='axis.service' paramName='scope' value='request,session,application' default='request'/>"/>

 </service>

</XDtClass:ifHasClassTag>

</XDtClass:forAllClasses>

</deployment>

Das Ant-Script steuert die Erzeugung des Deployment-Descriptor mit XDoclet und kann anschließend gleich das Deployment in das laufende Axis Anwendung hinein vornehmen. Hierzu werden aus der Axis-Distrubution die Ant-Tasks in axis-ant.jar eingebunden und mit der „Admin-Task“ das Deployment vorgenommen. Das Script wird noch parametriert über build.properties, welche alle lokalen Einstellungen enthält.

<project name="webmodulebuilder" default="axis-deploy" basedir=".">

 <!-- set global properties for this build -->
 <property file="build.properties"/>
 <property name="dist" value="../../dist" />
 <property name="web" value="../" />

 <property name="src" value="../../src/" />
 <property name="output" value="${basedir}" />

 <path id="xdoclet.class.path">
    <fileset dir="${xdocletlib.dir}">
        <include name="*.jar"/>
    </fileset>
 </path>

 <path id="axis.classpath">
     <!-- use the webapps lib path, where all axis jars are present -->
     <fileset dir="${basedir}/lib">
         <include name="**/*.jar" />
     </fileset>
 </path>

 <target name="axisdoclet">
         <taskdef
             name="templatedoclet"
             classname="xdoclet.DocletTask"
             classpathref="xdoclet.class.path"
         />

         <tstamp>
             <format property="TODAY" pattern="d-MM-yy"/>
         </tstamp>

         <templatedoclet destdir="${output}" verbose="1">
            <fileset dir="${src}">
                <include name="**/*.java" />
            </fileset>

            <template templateFile="axis-wsdd.xdt.xml" destinationFile="deploy.wsdd">
                <configParam name="Xmlencoding" value="utf-8" />
            </template>

         </templatedoclet>
 </target>

 <target name="axis-deploy" depends="axisdoclet">

     <taskdef resource="axis-tasks.properties" classpathref="axis.classpath" />

     <axis-admin
         port="${target.port}"
         hostname="${target.server}"
         failonerror="true"
         servletpath="${target.appname}/services/AdminService"
        debug="true"
         xmlfile="deploy.wsdd"
     />

 </target>
</project>

Welche WebServices gerade aktiviert sind kann jederzeit mit einem erneuten Aufruf der Axis-Seite /axis/servlet/AxisServlet abgefragt werden. Das Servlet verwendet übrigens ein XML-File „server-config.wsdd“ in dem alle „deployten“ Services aufgeführt sind. Wir ein neuer Service in Betrieb genommen, dann passt Axis diese Datei entsprechend an.

Deklariert die Klasse als WebService.

Deklariert die Klasse als Request-Handler. Sie muss von org.apache.axis.handlers.BasicHandler abgeleitet sein.

Deklariert einen Handler, den die WebService-Klasse benutzten soll. XDoclet fügt damit im Deployment-Descriptor ein Request-Flow Element ein, welches den/die Handler einbindet.

Deklariert einen Parameter, den die Handlerklasse erfragen kann.

Deklariert eine Methode als WebService-Methode. Für den Fall, dass auf Klassenebene nicht „include-all=true“ als Attribut angegeben wurde, kann so jede Methode einzeln als WebService-Methode deklariert werden.Axis Classpath wird von Lomboz immer auf die Plugin-Libs gesetzt, ersetzen durch die kompletten aktuellen Libs. Achtung bei 4.1.29 muss man im Sysdeo-Plugin bereits Tomcat 5.x einstellen.

Zum Einsatz kommen hier die im Artikel des Java-Magazins vorgeschlagenen Bibliotheken von IBM und VeriSign. IBMs Security Bibliothek ist sowohl in IBMs WebSphere SDK for Web Services (WSDK) als auch im Emerging Technologies Toolkit (ETTK) enthalten. Von den beiden recht grossen Downloads wird allerdings nur ibmjceprovider.jar und die ibmjlog.jar benötigt. Ich habe mir deshalb die Freiheit genommen und diese Bibliotheken direkt ins Beispiel-Projekt aufgenommen. Der reguläre Download umfasst viele Megabyte mehr an Daten und erfordert auch das Akzeptieren der Lizenzbedingungen näheres siehe:

Download WSDK from IBM:

http://www-106.ibm.com/developerworks/webservices/wsdk/

alternativ Download ETTK:

http://www.alphaworks.ibm.com/tech/ettk

Entsprechendes gilt für die Bibliotheken von VeriSign. Auch hier werden einfach nur die beiden Bibliotheken benutzt. Man kann die kompletten Pakete downloaden und nach der Installation die Bibliotheken kopieren und dann alles wieder entfernen.

Downloads von VeriSign:

VeriSign Trust Services Integration Kit (TSIK): http://www.xmltrustcenter.org/developer/verisign/tsik/index.htm

und

WS-Security Implementierung von VeriSign: http://www.xmltrustcenter.org/developer/verisign/dist/ws-security-1.7.zip

Schaut man sich die SOAP Nachrichten an, die bei der gesicherten Kommunikation ausgetauscht werden, so fällt auf dass die gesicherte Variante erheblich grösser ist und somit einigen Overhead erzeugt.

Vorher (ungesichert):

<soapenv:Envelope 

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsd="http://www.w3.org/2001/XMLSchema" 

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soapenv:Body>

<ns1:getAddress 

soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"

xmlns:ns1="http://service.solutions.rinke.de">

<id xsi:type="xsd:int">0</id>

</ns1:getAddress>

</soapenv:Body>

</soapenv:Envelope>

Nachher (gesichert):

<soapenv:Envelope 

xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:xsd="http://www.w3.org/2001/XMLSchema"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soapenv:Header>

<wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext">

<xenc:EncryptedKey xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">

<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>

<xenc:CipherData>

<xenc:CipherValue>

             dMjLSkUIzeDo7MxKg6lXtgQOwW2ZFDUUEhF/cKNY475FaxsCSwtAgfpMBlTBHf+jFYxIIq95

             29oVLNG8Sq8mbwYOCbEdkpIi7Eb8P8jV+rYn/Qiy12C6an0pqo5U18tffv2mDvnYW1V+SDVV

LiKR7ih2cGeY+AT0IiR0np1Apho=

</xenc:CipherValue>

</xenc:CipherData>

<xenc:ReferenceList>

<xenc:DataReference URI="#wsse-c6cf62d0-5ef8-11d8-8ffa-ada096a18c18"/>

</xenc:ReferenceList>

</xenc:EncryptedKey>

<wsse:BinarySecurityToken ValueType="wsse:X509v3" 

EncodingType="wsse:Base64Binary" 

wsu:Id="wsse-c64f0f40-5ef8-11d8-8ffa-ada096a18c18" 

xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">

           MIIB2TCCAUICBEAtZtMwDQYJKoZIhvcNAQEEBQAwNDELMAkGA1UEBhMCREUxFDASBgNVBAoT

           C1N0ZWZhblJpbmtlMQ8wDQYDVQQDEwZDbGllbnQwHhcNMDQwMjE0MDAwNzQ3WhcNMDQwNTE0

           MDAwNzQ3WjA0MQswCQYDVQQGEwJERTEUMBIGA1UEChMLU3RlZmFuUmlua2UxDzANBgNVBAMT

           BkNsaWVudDCBnjANBgkqhkiG9w0BAQEFAAOBjAAwgYgCgYB24AKhC8OqeTi0eXn2EP6uKWBe

           sIvye7q0wnewZ/X0uGXbBRvX0PH8JkTyopqwjwVMnJaGnbFbuQEezxLo5kctdSNoQSB628m+

           LT2rDkhiZqg5jIWqKIQXqXgg8EuBAg9hgoaR2Y3xex7eri72CfC7u2ICaPkqmIBlfkVZIwkK

           FwIDAQABMA0GCSqGSIb3DQEBBAUAA4GBAAgDbm4+zbK50QGACEHO2v+bM/v2uN/3wq5DxqNL

           wI1bgsRSVMGCaAq6HZUCTdqBDCcJlk2dOG+PETM0tP+bh/jM3yIpccV75qs3NTOQHZIP5v9Z

           ZbIb3wcHBLcJCuxf6ZLe/b6IuibcQfz4JwuxifBhG0BbKMTuCvk7adqcPawx

</wsse:BinarySecurityToken>

<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

<ds:SignedInfo>

<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>

<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>

<ds:Reference URI="#wsse-c60730d0-5ef8-11d8-8ffa-ada096a18c18">

<ds:Transforms>

<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>

</ds:Transforms>

<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>

<ds:DigestValue>VO6yW5RrFZA+sr3QYDFYjIcyuwI=</ds:DigestValue>

</ds:Reference>

<ds:Reference URI="#wsse-c5ff8fb0-5ef8-11d8-8ffa-ada096a18c18">

<ds:Transforms>

<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>

</ds:Transforms>

<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>

<ds:DigestValue>CYvLe0Wv0mJ6bPvGfapUP5ahtgU=</ds:DigestValue>

</ds:Reference>

</ds:SignedInfo>

<ds:SignatureValue>

           VvClhOxjXyIlrGi3BS9yc4Nm/40N+/vKgHIxtjTOVIueqggVhSym7U01C6RC1je+WS1yRNdU

           9eGoKTlPrNbqgL4txN3X5OTDhJaxMpf6IGdsVd+UikXJoN0+OcmJVRQd4bUqraIZrmeEWbVz

ZGACIe297cBZZ1KTHary6z1Vs9Y=

</ds:SignatureValue>

<ds:KeyInfo>

<wsse:SecurityTokenReference>

<wsse:Reference URI="#wsse-c64f0f40-5ef8-11d8-8ffa-ada096a18c18"/>

</wsse:SecurityTokenReference>

</ds:KeyInfo>

</ds:Signature>

</wsse:Security>

<wsu:Timestamp xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">

<wsu:Created wsu:Id="wsse-c5ff8fb0-5ef8-11d8-8ffa-ada096a18c18">

         2004-02-14T14:19:17Z

</wsu:Created>

</wsu:Timestamp>

</soapenv:Header>

<soapenv:Body wsu:Id="wsse-c60730d0-5ef8-11d8-8ffa-ada096a18c18" 

xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility">

<xenc:EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Content" 

xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" 

Id="wsse-c6cf62d0-5ef8-11d8-8ffa-ada096a18c18">

<xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#tripledes-cbc"/>

<xenc:CipherData>

<xenc:CipherValue>

           uMNGMbCMiAruKyx42I1C/5iYQxnt1W575l/Dvpm2v2cRIN0JgQtCPQQxmhYhXePH28dtct+W

           V2VzWeNDrd2LjGjh5tiRMOecZLQ78rQ7/uy6aLn/OcLOiOucJ61kB2+B1V36P7R1a64Gizak

           u54FB4qQJloWrme5FFqdVVh3c2PS0gtKcefoYIrPygmhtbayFRJNyZiRxvSDrrlYuTYgsTmN

d3hQuWKTr9cOPXExWp31NJ8Mp/Ir2/XgNawrPVTurF2qTOa+tsw=

</xenc:CipherValue>

</xenc:CipherData>

</xenc:EncryptedData>

</soapenv:Body>

</soapenv:Envelope>

Wenn man diese enorm grosse XML-Message anschaut, fragt man sich allerdings, ob nicht besser doch ein binäres Protokoll angezeigt wäre ;-). Einer der Vorteile - nämlich die Lesbarkeit der XML-Nachrichten – ist hier jedenfalls nicht mehr vorhanden.