Home > Services

Web Services

This chapter describes how to implement Web Services on the webMethods MDM side, offering the ability for any software client to interact with webMethods MDM through SOAP (Simple Object Access Protocol) messages.

We will go through the following steps:

  • Install Axis, an open source implementation of SOAP
  • Implement an import/export Web Service
  • Develop a client to invocate the Web Service

    •  

    Step 1 - Install Axis

    Axis is available here.

    We've been using version 1.4 of Axis to implement our Web Services.
    Please download the version from one of the mirror site and install (unzip) it on your computer.

    As of now, we assume Axis is installed on <your install dir>.

    Step 2 - Deploy Axis on the web server

    We need to deploy Axis on the same web server as webMethods MDM for them to interact.

    Here we assume that you have a web server up and running on the localhost at port 8080. This is where webMethods MDM has been generally deployed. If your server is on a different port, please replace references to 8080 with your own port number.

    In your Application Server installation, you should find a directory into which web applications ("webapps") are to be placed. Into this directory, copy the <your install dir>/webapps/axis directory from the axis distribution. You can actually name this directory anything you want, just be aware that the name you choose will form the basis for the URL by which clients will access your service. The rest of this document assumes that the default webapp name, "axis" has been used; please rename these references if appropriate.

    You need to declare the axis webapp in the Application Server web.xml file, under the Host tag:

    <Context path="/axis" docBase="<path to webapps/axis>" />

    This way, webMethods MDM and axis webapps will collaborate under the same Application Server.

    You can test your configuration using this link.

    Step 3 - Create a Web Service

    Let's create our first Web Service using Axis. This Service will give the ability to access to operations : import and export.

    These two operations:

  • have login and password parameters in order to login webMethods MDM
  • have an adaptation name parameter to identify the webMethods MDM adaptation to import to or export from
    • JavaDoc
  • use webMethods MDM Programmatic Service and Procedure classes
  • return a string argument containing the result (a user message for the import and the data exported/error message for the export)

    • package com.softwareag.mdm.webservices;

    import java.io.*;

    import com.softwareag.mdm.adaptation.*;
    import com.softwareag.mdm.service.*;

    public class mdmWebService
    {
        public String importMethod(String login, String password, String adaptationName, String data)
        {
            String summary;
            final Adaptation ada = AdaptationName.forName(adaptationName).resolve();
            if (ada == null)
            {
                summary = "Unknown adaptation " + adaptationName;
                return summary;
            }

            // Creates a container for runnning services 
            ProgrammaticService svc = ProgrammaticService.createForLogin(login, password);
            svc.setSessionTrackingInfo("Import WebService");
            final StringBuffer msg = new StringBuffer();

            final ImportSpec is = new ImportSpec();
            is.setSourceStream(new ByteArrayInputStream(data.getBytes()));
            is.setTargetAdaptation(ada);

            // Defines the procedure 
            Procedure proc = new Procedure()
            {
                public void execute(ProcedureContext aContext) throws Exception
                {
                    aContext.doImport(is);
                    msg.append("Data has been imported into adaptation [" + ada.toPublicReference()
                        + "].");
                }
            };
            // Requests the execution in the container and handles the result 
            ProcedureResult result = svc.execute(proc);
            if (result.hasFailed())
                summary = "Exception: " + result.getException();
            else
                summary = "Execution successful: " + msg;

            return summary;
        }

        public String exportMethod(String login, String password, String adaptationName)
        {
            ByteArrayOutputStream stream = new ByteArrayOutputStream();
            String summary;
            final Adaptation ada = AdaptationName.forName(adaptationName).resolve();
            if (ada == null)
            {
                summary = "Unknown adaptation " + adaptationName;
                return summary;
            }

            // Creates a container for running services 
            ProgrammaticService svc = ProgrammaticService.createForLogin(login, password);
            svc.setSessionTrackingInfo("Export WebService");

            final ExportSpec es = new ExportSpec();
            es.setDestinationStream(stream);
            es.setSourceAdaptation(ada);
            es.setContentIndented(true);

            // Defines the procedure 
            Procedure proc = new Procedure()
            {
                public void execute(ProcedureContext aContext) throws Exception
                {
                    aContext.doExport(es);
                }
            };
            // Requests the execution in the container and handles the result 
            ProcedureResult result = svc.execute(proc);
            if (result.hasFailed())
                summary = "Exception: " + result.getException();
            else
                summary = stream.toString();

            return summary;
        }

    }

    Step 4 - Deploy the Web Service

    The class we have just set up implements the Web Service. What remains to be done is to tell Axis how to expose this web service. Axis takes a Web Service Deployment Descriptor (WSDD) file that describes in XML what the service is, what methods it exports and other aspects of the SOAP endpoint.

    The Axis user guide and reference guide cover these WSDD files.

    Here is our deploy.wsdd file:

    <deployment xmlns="http://xml.apache.org/axis/wsdd/"
        xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
      <service name="mdmWebService" provider="java:RPC">
        <requestFlow> 
           <handler type="soapmonitor"/> 
         </requestFlow> 
         <responseFlow> 
           <handler type="soapmonitor"/> 
         </responseFlow>  
        <parameter name="className" value="com.softwareag.mdm.webservices.mdmWebService"/>
        <parameter name="allowedMethods" value="*"/>
      </service>
    </deployment>

    .. and the corresponding undeploy.wsdd file:

    <undeployment xmlns="http://xml.apache.org/axis/wsdd/">
     <service name="mdmWebService"/>
    </undeployment>


    To deploy/undeploy the Web Service under Axis, please run Java with the following parameters:

    main class: org.apache.axis.client.AdminClient

    arguments:-lhttp://localhost:8080/axis/services/AdminService "<path to the wsdd file> "

    Now the Web Service is ready to be called.

    Step 5 - Create a Web Service client

    Below are java code examples that illustrate how to consume the preceding Web Service using Axis.

    Please refer to the Axis documentation for some more information about the java classes and methods used in our Axis client classes.

  • Export client:

    • package com.softwareag.mdm.webservices;

    import java.io.*;

    import org.apache.axis.client.Call;
    import org.apache.axis.client.Service;
    import org.apache.axis.encoding.*;
    import org.apache.axis.utils.Options;

    import javax.xml.namespace.QName;
    import javax.xml.rpc.*;

    public class ClientExport
    {
        public static void main(String [] args)
        {
            try {
                Options options = new Options(args);
                
                String endpointURL = options.getURL();
                
                args = options.getRemainingArgs();
                String user;
                String password;
                String adaptation;
                String file;
                
                if ((args == null) || (args.length < 4)) 
                {
                    System.out.println("Usage: client <user> <password> <adaptation reference> <file to export to>");
                    return;
                } 
                else 
                {
                    user = args[0];
                    password = args[1];
                    adaptation = args[2];
                    file = args[3];
                }
                
                Service  service = new Service();
                Call     call    = (Call) service.createCall();

                call.setTargetEndpointAddress( new java.net.URL(endpointURL) );
                call.setOperationName( new QName("http://webservices.softwareag.com", "exportMethod") );
                call.addParameter( "user", XMLType.XSD_STRING, ParameterMode.IN);
                call.addParameter( "password", XMLType.XSD_STRING, ParameterMode.IN);
                call.addParameter( "adaptation", XMLType.XSD_STRING, ParameterMode.IN);
                call.setReturnType(XMLType.XSD_STRING );

                String ret = (String) call.invoke( new Object[] { user,password,adaptation} );

                FileOutputStream fos = new FileOutputStream(file);
                fos.write(ret.getBytes());
                fos.flush();
                fos.close();
                
                System.out.println("Return message from export service: " + ret);
            } 
            catch (Exception e)
            {
                System.err.println(e.toString());
            }
        }
    }

    In order to execute the code, please run Java with the following parameters:

  • main class: com.softwareag.mdm.webservices.ClientExport

    arguments: -lhttp://localhost:8080/axis/services/mdmWebService "<user>" "<password>" "<your adaptation reference>" "<path to the xml file to export to> "

  • Import client:

    • package com.softwareag.mdm.webservices;

    import java.io.*;

    import org.apache.axis.client.Call;
    import org.apache.axis.client.Service;
    import org.apache.axis.encoding.*;
    import org.apache.axis.utils.Options;

    import javax.xml.namespace.QName;
    import javax.xml.rpc.*;

    public class ClientImport
    {
        public static void main(String [] args)
        {
            try {
                Options options = new Options(args);
                
                String endpointURL = options.getURL();
                
                args = options.getRemainingArgs();
                String user;
                String password;
                String adaptation;
                String file;
                
                if ((args == null) || (args.length < 4)) 
                {
                    System.out.println("Usage: client <user> <password> <adaptation reference> <file to import from>");
                    return;
                } 
                else 
                {
                    user = args[0];
                    password = args[1];
                    adaptation = args[2];
                    file = args[3];
                }
                
                LineNumberReader reader = new LineNumberReader(new FileReader(file));
                StringBuffer sb = new StringBuffer();
                
                String line;
                while ((line= reader.readLine())!=null)
                {
                    sb.append(line);
                }
                String stream =sb.toString();
                
                Service  service = new Service();
                Call     call    = (Call) service.createCall();

                call.setTargetEndpointAddress( new java.net.URL(endpointURL) );
                call.setOperationName( new QName("http://webservices.softwareag.com", "importMethod") );
                call.addParameter( "user", XMLType.XSD_STRING, ParameterMode.IN);
                call.addParameter( "password", XMLType.XSD_STRING, ParameterMode.IN);
                call.addParameter( "adaptation", XMLType.XSD_STRING, ParameterMode.IN);
                call.addParameter( "data", XMLType.XSD_STRING, ParameterMode.IN);
                call.setReturnType( org.apache.axis.encoding.XMLType.XSD_STRING );

                String ret = (String) call.invoke( new Object[] { user,password,adaptation,stream } );
                
                System.out.println("Return message from import service: " + ret);
            } 
            catch (Exception e)
            {
                System.err.println(e.toString());
            }
        }
    }

    In order to execute the code, please run Java with the following parameters:

    main class: com.softwareag.mdm.webservices.ClientImport

    arguments: -lhttp://localhost:8080/axis/services/mdmWebService "<user>" "<password>" "<your adaptation reference>" "<path to the xml file to import from>"

    Note - Instant deployment

    Axis gives the ability to instantly deploy any java code as a web service. Please refer to the corresponding Axis users's guide chapter for some more information.
    Simply put : if you copy any <source.java> Java source code into <your webapp root>/axis /<source.jws>, Axis automatically locates the file, compiles the class, and converts SOAP calls correctly into Java invocations of your service class.

    Then, the corresponding web service is ready to be used. (Check http://localhost:8080/axis/<source.jws>?wsdl to get the wsdl file).

     

    Services Web

    Ce chapitre décrit comment implémenter des Web Services côté MDM, offrant la possibilité à tout client logiciel d'interagir avec webMethods MDM à travers des messages SOAP (Simple Object Access Protocol ).

    Nous allons décrire les étapes suivantes :

  • Installation d'Axis, une implémentation de SOAP libre de droits
  • Implementer un Web Service d'import/export
  • Développer un client pour invoquer le Web Service

    •  

    Etape 1 - Installation d'Axis

    Axis est disponible ici.

    Nous avons utilisé la version 1.4 d'Axis pour implémenter nos Web Services.
    Téléchargez SVP la version à partir d'un site mirroir et installez (dézippez) le fichier sur votre disque dur.

    A partir de maintenant, nous partons du principe qu'Axis est installé dans le répertoire <votre répertoire d'installation>.

    Etape 2 - Déploiement d'Axis sur le serveur web

    Nous devons déployer Axis sur le serveur web où webMethods MDM est installé pour permettre leur interaction.

    Nous faisons ici l'hypothèse que vous avez un serveur web qui s'exécute sur localhost au port 8080. C'est ici qu'webMethods MDM est généralement installé. Si votre serveur est sur un port différent, veuillez remplacer les références au port 8080 avec votre propre numéro de port.

    Dans le répertoire d'installation de votre serveur d'application, vous devriez trouver un répertoire dans lequel les applications web ("webapps") doivent être installées. Dans ce répertoire, veuillez copier le répertoire <votre répertoire d'installation>/webapps/axis en provenance de la distribution axis téléchargée précédemment. Vous pouvez appeler ce répertoire comme bon vous semble, soyez juste prudent sur le fait que le nom choisi sera utilisé pour la construction de l'URL de base par laquelle les clients accèderont à vos services. Dans le reste de ce document, nous partons du principe que vous avez utilisé "axis" comme nom de webapp par défaut; veuillez renommer ces références si nécessaire.

    Vous devez déclarer la webapp axis dans le fichier web.xml du serveur d'application, sous la balise Host :

    <Context path="/axis" docBase="<chemin vers webapps/axis>" />

    De cette façon, les webapps webMethods MDM et axis collaboreront dans le même serveur d'application.

    Vous pouvez tester votre configuration en utilisant le lien.

    Etape 3 - Créer un Web Service

    Créons notre premier Web Service utilisant Axis. Ce Service donnera la possibilité d'accès aux opérations d'import et export.

    Les deux opérations :

  • disposent de paramètres login et mot de passe pour se connecter à webMethods MDM
  • ont un paramètre adaptationName pour identifier l'adaptation dans webMethods MDM à partir de laquelle on importe ou exporte
    • JavaDoc
  • utilisent les Services Programmatiques webMethods MDM et la classe Procedure
  • retournent un argument de type chaîne de caractères contenant le résultat (un message utilisateur pour l'import et les données exportées/message d'erreur pour l'export)

    • package com.softwareag.mdm.webservices;

    import java.io.*;

    import com.softwareag.mdm.adaptation.*;
    import com.softwareag.mdm.service.*;

    public class mdmWebService
    {
        public String importMethod(String login, String password, String adaptationName, String data)
        {
            String summary;
            final Adaptation ada = AdaptationName.forName(adaptationName).resolve();
            if (ada == null)
            {
                summary = "Unknown adaptation " + adaptationName;
                return summary;
            }

            // Creates a container for running services 
            ProgrammaticService svc = ProgrammaticService.createForLogin(login, password);
            svc.setSessionTrackingInfo("Import WebService");
            final StringBuffer msg = new StringBuffer();

            final ImportSpec is = new ImportSpec();
            is.setSourceStream(new ByteArrayInputStream(data.getBytes()));
            is.setTargetAdaptation(ada);

            // Defines the procedure 
            Procedure proc = new Procedure()
            {
                public void execute(ProcedureContext aContext) throws Exception
                {
                    aContext.doImport(is);
                    msg.append("Data has been imported into adaptation [" + ada.toPublicReference()
                        + "].");
                }
            };
            // Requests the execution in the container and handles the result 
            ProcedureResult result = svc.execute(proc);
            if (result.hasFailed())
                summary = "Exception: " + result.getException();
            else
                summary = "Execution successful: " + msg;

            return summary;
        }

        public String exportMethod(String login, String password, String adaptationName)
        {
            ByteArrayOutputStream stream = new ByteArrayOutputStream();
            String summary;
            final Adaptation ada = AdaptationName.forName(adaptationName).resolve();
            if (ada == null)
            {
                summary = "Unknown adaptation " + adaptationName;
                return summary;
            }

            // Creates a container for running services 
            ProgrammaticService svc = ProgrammaticService.createForLogin(login, password);
            svc.setSessionTrackingInfo("Export WebService");

            final ExportSpec es = new ExportSpec();
            es.setDestinationStream(stream);
            es.setSourceAdaptation(ada);
            es.setContentIndented(true);

            // Defines the procedure 
            Procedure proc = new Procedure()
            {
                public void execute(ProcedureContext aContext) throws Exception
                {
                    aContext.doExport(es);
                }
            };
            // Requests the execution in the container and handles the result 
            ProcedureResult result = svc.execute(proc);
            if (result.hasFailed())
                summary = "Exception: " + result.getException();
            else
                summary = stream.toString();

            return summary;
        }

    }

    Etape 4 - Déploiement du Web Service

    La classe que nous venons de créer réalise le Web Service. Il ne nous reste plus qu'à indiquer à Axis comment exposer ce web service. Axis utilise un fichier Web Service Deployment Descriptor (WSDD) qui décrit en XML ce qu'est le service, quelles méthodes il expose et d'autres aspects de SOAP.

    Le guide utilisateur et le guide de référence Axis couvrent la description de ces fichiers WSDD.

    Voici notre fichier de déploiement deploy.wsdd :

    <deployment xmlns="http://xml.apache.org/axis/wsdd/"
        xmlns:java="http://xml.apache.org/axis/wsdd/providers/java">
      <service name="mdmWebService" provider="java:RPC">
        <requestFlow> 
           <handler type="soapmonitor"/> 
         </requestFlow> 
         <responseFlow> 
           <handler type="soapmonitor"/> 
         </responseFlow>  
        <parameter name="className" value="com.softwareag.mdm.webservices.mdmWebService"/>
        <parameter name="allowedMethods" value="*"/>
      </service>
    </deployment>

    et le fichier d'annulation du déploiement undeploy.wsdd :

    <undeployment xmlns="http://xml.apache.org/axis/wsdd/">
     <service name="mdmWebService"/>
    </undeployment>


    Pour déployer/annuler le Web Service sous Axis, veuillez lancer la commande Java avec les paramètres suivants :

    classe principale: org.apache.axis.client.AdminClient

    arguments:-lhttp://localhost:8080/axis/services/AdminService "<chemin vers le fichier wsdd> "

    Le Web Service est maintenant prêt à être appelé.

    Etape 5 - Créer un client à notre Web Service

    Vous trouverez ci-dessous des exemples de code Java qui illustrent comment utiliser les Web Services précédents sous Axis.

    Veuillez vous référer à la documentation Axis pour de plus amples informations à propos des classes et méthodes Java utilisées dans l'implémentation de notre client Axis.

  • Client d'export:

    • package com.softwareag.mdm.webservices;

    import java.io.*;

    import org.apache.axis.client.Call;
    import org.apache.axis.client.Service;
    import org.apache.axis.encoding.*;
    import org.apache.axis.utils.Options;

    import javax.xml.namespace.QName;
    import javax.xml.rpc.*;

    public class ClientExport
    {
        public static void main(String [] args)
        {
            try {
                Options options = new Options(args);
                
                String endpointURL = options.getURL();
                
                args = options.getRemainingArgs();
                String user;
                String password;
                String adaptation;
                String file;
                
                if ((args == null) || (args.length < 4)) 
                {
                    System.out.println("Usage: client <user> <password> <adaptation reference> <file to export to>");
                    return;
                } 
                else 
                {
                    user = args[0];
                    password = args[1];
                    adaptation = args[2];
                    file = args[3];
                }
                
                Service  service = new Service();
                Call     call    = (Call) service.createCall();

                call.setTargetEndpointAddress( new java.net.URL(endpointURL) );
                call.setOperationName( new QName("http://webservices.softwareag.com", "exportMethod") );
                call.addParameter( "user", XMLType.XSD_STRING, ParameterMode.IN);
                call.addParameter( "password", XMLType.XSD_STRING, ParameterMode.IN);
                call.addParameter( "adaptation", XMLType.XSD_STRING, ParameterMode.IN);
                call.setReturnType(XMLType.XSD_STRING );

                String ret = (String) call.invoke( new Object[] { user,password,adaptation} );

                FileOutputStream fos = new FileOutputStream(file);
                fos.write(ret.getBytes());
                fos.flush();
                fos.close();
                
                System.out.println("Return message from export service: " + ret);
            } 
            catch (Exception e)
            {
                System.err.println(e.toString());
            }
        }
    }

    Pour exécuter le code, veuillez lancer la commande Java avec les paramètres suivants :

  • classe principale : com.softwareag.mdm.webservices.ClientExport

    arguments: -lhttp://localhost:8080/axis/services/mdmWebService "<utilisateur>" "<mot de passe >" "<référence de l'adaptation à exporter >" "<chemin vers le fichier xml cible > "

  • Client d' Import :

    • package com.softwareag.mdm.webservices;

    import java.io.*;

    import org.apache.axis.client.Call;
    import org.apache.axis.client.Service;
    import org.apache.axis.encoding.*;
    import org.apache.axis.utils.Options;

    import javax.xml.namespace.QName;
    import javax.xml.rpc.*;

    public class ClientImport
    {
        public static void main(String [] args)
        {
            try {
                Options options = new Options(args);
                
                String endpointURL = options.getURL();
                
                args = options.getRemainingArgs();
                String user;
                String password;
                String adaptation;
                String file;
                
                if ((args == null) || (args.length < 4)) 
                {
                    System.out.println("Usage: client <user> <password> <adaptation reference> <file to import from>");
                    return;
                } 
                else 
                {
                    user = args[0];
                    password = args[1];
                    adaptation = args[2];
                    file = args[3];
                }
                
                LineNumberReader reader = new LineNumberReader(new FileReader(file));
                StringBuffer sb = new StringBuffer();
                
                String line;
                while ((line= reader.readLine())!=null)
                {
                    sb.append(line);
                }
                String stream =sb.toString();
                
                Service  service = new Service();
                Call     call    = (Call) service.createCall();

                call.setTargetEndpointAddress( new java.net.URL(endpointURL) );
                call.setOperationName( new QName("http://webservices.softwareag.com", "importMethod") );
                call.addParameter( "user", XMLType.XSD_STRING, ParameterMode.IN);
                call.addParameter( "password", XMLType.XSD_STRING, ParameterMode.IN);
                call.addParameter( "adaptation", XMLType.XSD_STRING, ParameterMode.IN);
                call.addParameter( "data", XMLType.XSD_STRING, ParameterMode.IN);
                call.setReturnType( org.apache.axis.encoding.XMLType.XSD_STRING );

                String ret = (String) call.invoke( new Object[] { user,password,adaptation,stream } );
                
                System.out.println("Return message from import service: " + ret);
            } 
            catch (Exception e)
            {
                System.err.println(e.toString());
            }
        }
    }

    Pour exécuter le code, veuillez lancer la commande Java avec les paramètres suivants :

    classe principale : com.softwareag.mdm.webservices.ClientImport

    arguments: -lhttp://localhost:8080/axis/services/mdmWebService "<utilisateur>" "<mot de passe>" "<référence de l'adaptation où importer>" "<chemin vers le fichier xml source >"

    Note - Déploiement instantané

    Axis donne la possibilité de déployer en un clin d'oeil tout code source Java en un web service. Veuillez vous référer au chapitre correspondant dans le guide de l'utilisateur Axis pour de plus amples informations.
    Pour résumer, si vous copiez n'importe quel code source Java <source.java> vers <racine de la webapp >/axis /<source.jws>, Axis détecte automatiquement le fichier, compile la classe, et convertit correctement les appels SOAP en invocations Java de votre classe service.

    Ainsi, le web service correspondant est prêt à être utilisé (Cf http://localhost:8080/axis/<source.jws>?wsdl pour récupérer le fichier wsdl).

     

    Home > Services