Since the XML APIs were developed using Workshop, it is not possible to migrate them using a tool. Therefore, the best way to migrate these XML APIs to web services is to write them in Java.

Figure 2-1 describes an overview of the migration steps.

Figure 2-1 Overview of Migration Steps Using Java

Description of "Figure 2-1 Overview of Migration Steps Using Java"

The following steps show an example of how to write Java functionality for a sample XML API:

1. Create a WSDL File. This step assumes you are using Java Process Definition (JPD) for your integration.

   1. For your XML API, get the WSDL file for the API which must be migrated.

   2. Find your JPD file (these have a .jpd or .java extension) for the XML API you are converting. You can get the WSDL file by adding “?WSDL" after the JPD file information.

      http://hostname:port/custom/testAPI.jpd?WSDL

   This will give you the complete WSDL for your JPD file.

   Note:

   In WebLogic Integration, Process Definition for Java (JPD) defines a business process.

2. Save the file to a new name, for example: testAPI.wsdl.

3. Set up your WebLogic Server and MSS environment.

   Open a command window and execute the setDomainEnv.cmd (Windows) or setDomainEnv.sh (UNIX) script, located in the bin subdirectory of your domain directory.

4. Create a working directory, for example:

   c:\opt\customWebService

   where customWebService is the name of the XML API that you want to migrate.

5. Put your WSDL file into an accessible directory on your computer.

   In this example, it is assumed that your WSDL file is called testAPI.wsdl and place the WSDL file in the '\customWebService \wsdl_file' directory.

6. Create a standard Ant build.xml file in the project directory. Set up the values of the property names for items such as the URL, server name, and password.

   <project name="GenerateWS" default="all">
   <property name="build" value="output" />
   <property name="adminurl" value="t3://192.0.2.251:7001"/> //Server IP & Port
   <property name="serverName" value="m63server" /> // Server Name
   <property name="userName" value="weblogic" /> // User Name
   <property name="password" value="password" /> // Password
   <property name="ear.name" value="Custom_WebService" /> // Ear Name

   In this example, the build.xml file will be located under the c:\opt\customWebService directory.

   See "Sample Build XML File" for an example of a complete build.xml file.

7. Add a taskdef item to specify the full Java classname of the wsdlc task.

   <taskdef name="jwsc" classname="weblogic.wsee.tools.anttasks.JwscTask" />
   <taskdef name="wsdlc" classname="weblogic.wsee.tools.anttasks.WsdlcTask"/>

8. Create a generate-from-wsdl target and add the following to the wsdlc Ant task in the build.xml file:

   <target name="generate-from-wsdl">
        <wsdlc srcWsdl="wsdl_file/testAPI.wsdl"
               destJwsDir="jarJws"
               destImplDir="src" type="JAXWS"
               packageName="custom.mss.test"/>
   </target>

   Before generating the web service from WSDL file, the following changes need to be made on the MSS WSDL file for a successful compilation:

   • Remove one <wsdl:port> which contains the name with JpdSoap under <wsdl:services>.

   • Remove the corresponding <wsdl:binding> for JpdSoap.

   • Remove the corresponding <wsdl:port type> for JpdSoap.

   • Remove the corresponding <wsdl:message> for both Input and Output messages.

9. Execute the generate-from-wsdl target to run the wsdlc Ant task by running this command line:

   ant generate-from-wsdl

   See the output directory to examine the artifacts and files generated by the wsdlc Ant task.

   The wsdlc task in the examples generates the JAR file that contains the JWS Service Endpoint Interface (SEI) and JAXB data binding artifacts into the jarJws directory under the current directory.

   It also generates a partial implementation file (testAPISoapImpl.java) of the JWS SEI into the src\custom\mss\test\ directory (which is a combination of the output directory specified by destImplDir and the directory hierarchy specified by the package name). All generated JWS files will be packaged in the custom.mss.test package.

10. Update the implementation file.

    1. Run the wsimport Java command to generate the web service client files. The wsimport command creates JAX-WS portable artifacts that can be packaged in a web application archive or WAR file.

       Refer to the following website for more information on the wsimport command:

       https://docs.oracle.com/javase/8/docs/technotes/tools/unix/wsimport.html

    2. Package the generated files with the web service project or package it as a JAR file and include it as a library.

    3. Create a transaction to use for the API calls and do a lookup for the UserTransaction.

       ctx = new InitialContext(env);
       utx = (UserTransaction)
             ctx.lookup("javax.transaction.UserTransaction");

       where the env variable contains the server information.

    4. Add code to convert the API input object to an MSS input object. (This is the same concept as xquery converter logic in Workshop.) This is an example passing an input document number of type String to the Start Order input object.

       StartOrderByKeyRequest startOrderByKeyReq = 
           new StartOrderByKeyRequest();
       MetaSolvOrderKeyChoice metaSolvOrderKeyChoi = 
           new MetaSolvOrderKeyChoice();
       OrderKey ordKey = new OrderKey();
       ordKey.setPrimaryKey("11111");
       ordKey.setType("String");

    5. Initialize the web service port.

       OrderSoap ord = getWebService();

       The getWebService() method is a separate method and contains the Atomic Transaction along with the web service reference which points to the server WSDL file. The @Transactional and @WebServiceRef are annotations used by the getWebService() method.

       @Transactional(value = Transactional.TransactionFlowType.SUPPORTS,
                       version = Transactional.Version.DEFAULT);
       @WebServiceRef(wsdlLocation =
                       "http://ipaddress:port/MssWS/order/Order?WSDL",
                       value =  client.Order.class)Order service;
       
       private OrderSoap getWebService() {
          return service.getOrderSoap();
       }

       The client.Order.class is the Order class generated by wsimport command.

    6. Start the transaction.

       utx.begin();

    7. Secure the web service port using the credentials.

       List<CredentialProvider> credProviders = 
             new ArrayList<CredentialProvider>();
       String username = "username";
       String password = "password";
       CredentialProvider cp =
           new ClientUNTCredentialProvider(username.getBytes(),
                                           password.getBytes());
       credProviders.add(cp);
       Map<String, Object> rc = ((BindingProvider)ord).getRequestContext();
       rc.put(WSSecurityContext.CREDENTIAL_PROVIDER_LIST, credProviders);

    8. Invoke the web service operation. For instance, call the start order by key web service.

       StartOrderByKeyResponse StartOrderByKeyRes =
            ord.startOrderRequest(startOrderByKeyReq);

    9. Map the MSS response object to the custom response object using converter logic.

    10. Close the transaction.

        utx.commit();

    Note:

    In addition to these steps, ensure that all exceptions are handled properly using a catch block, and throw the error encountered.

    For multiple operations, you must repeat these steps and the transaction has to be handled.

11. Build the web service.

    1. Add a build-service target to the build.xml file that executes the jwsc Ant task against the updated JWS implementation class. Use the compiledWsdl attribute of jwsc task to specify the name of the JAR file generated by the wsdlc Ant task:

       <target name="build-service">
            <mkdir dir="${build}/${ear.name}" />
            <jwsc srcdir="src" destdir="${build}/${ear.name}">
                 <jws file="src/custom/mss/test/testAPISoapImpl.java" com-piledWsdl="jarJws/testAPI_wsdl.jar" type="JAXWS"/>
            </jwsc>
       </target>

    2. Ensure you have the wsimport client class files or the JAR file in the classpath. This is required to successfully compile the implementation files.

    3. After adding the build-service target, go to command prompt and run the following command

       ant build-service

    This will compile the web service class that contains the business logic.

12. Generate the custom web service EAR file using build.deliverable target.

    <target name="build.deliverable" depends="build-service" 
            description="Generates the WebService EAR">
      <delete file="Custom_WebService.ear"/>
      <ear destfile="Custom_WebService.ear"
       appxml="descriptors/META-INF/application.xml">
      <fileset dir="output/${ear.name}">
        <include name="**"/>
      </fileset>
      </ear>
    </target>

    This target creates an EAR file using the contents in output/earFileName directory.

13. Deploy the EAR file on the server:

    1. Deploy the web service, packaged in an Enterprise Application, to WebLogic Server, using the wldeploy Ant task.

    2. To use the wldeploy Ant task, add the following target to the build.xml file:

       <taskdef name="wldeploy"
                  classname="weblogic.ant.taskdefs.management.WLDeploy"/>
         <target name="deploy">
           <wldeploy action="deploy" name="wsdlcEar"
             source="output/wsdlcEar" user="${username}"
             password="${password}" verbose="true"
             adminurl="t3://${hostname}:${port}"
             targets="${server.name}" />
         </target>

       Substitute the values for username, password, hostname, port, and server.name that correspond to your WebLogic Server instance.

    3. Deploy the file by executing the deploy target:

       ant deploy

14. Test that the web service is deployed correctly by invoking its WSDL in your browser:

    http://hostname:port/custom/mss/test/testAPI?WSDL

    The context path and service URI section of the preceding URL are specified by the original WSDL. Use the hostname and port relevant to your WebLogic Server instance. The deployed and original WSDL files are the same, except for the host and port of the endpoint address.

For more information on “Developing JAX-WS Web Services for Oracle WebLogic Server", refer to the following Oracle WebLogic Server website:

For 12.2.1.4: https://docs.oracle.com/en/middleware/fusion-middleware/weblogic-server/12.2.1.4/wsget/jax-ws-setenv.html

Oracle SOA Suite enables system developers to set up and manage services and to orchestrate them into composite applications and business processes. Oracle SOA Suite runs on the same platform as WebLogic Integration (WebLogic Server).

To migrate a Workshop project to an Oracle SOA Suite project, you must design and build it. In Oracle SOA Suite, workflows are defined as Business Process Execution Language (BPEL) files. You create these files in the same way as you create JPD files in Workshop. Oracle SOA Suite has features which are similar to Workshop features that assist in the design process of workflows.

See the following website for information on the community of joint WLI/SOA users and the “SOA Suite Essentials for WLI users" series:

https://www.oracle.com/technical-resources/articles/middleware/soa-wli-bpel-transactions.html

Often you can have a call to an XML API as part of integration code that may call into several different systems. This section addresses how a simple Java class can invoke MSS Web Services.

The following steps show an example of how to write a Java class to invoke MSS Web Services:

1. Create a Java class with a main method that invokes another method, for example getOrderDetails(). The getOrderDetails() method calls the web service to retrieve order details and also contains the invocation logic.

   public static void main(String[] args)  {
      getOrderDetails();
   }

2. Create the method getOrderDetails() that invokes the MSS Web Service.

3. The first step of this method is to determine the WSDL URL and add a definition for that string variable. For instance, the following contains a line of code with a sample URL format for the Order Web Service:

   String url = "http://username:password@ipAddress:port/MssWS/order/Order?WSDL";

   where:

   • username is the username to log in to the web service

   • password is the password to log in to the web service

   • ipAddress is the IP Address for the WSDL location, such as 192.0.2.12

   • port is the port for the WSDL location, such as 1521

4. Define the soap message which is passed in as input XML.

   Note:

   The input XML can be read in from a file. These details are included to illustrate how the input message is built.

   MessageFactory mf = MessageFactory.newInstance();
   SOAPMessage message = mf.createMessage();
   SOAPPart soapPart = message.getSOAPPart();

5. Define the message header with the XML namespaces and add these to the envelope.

   /* XML NameSpaces */
   String soapenv = "http://schemas.xmlsoap.org/soap/envelope/";
   String open="http://www.openuri.org/";
   String ord="http://xmlns.oracle.com/communications/mss/OrderManagementAPI";
   String ord1="http://xmlns.oracle.com/communications/mss/OrderManagementEntities";
   String com="http://java.sun.com/products/oss/xml/Common";
   String wsse = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd";
   String wsu = "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd";
   
   /* Adding Name Spaces to the Envelope */
   SOAPEnvelope envelope = soapPart.getEnvelope();
   envelope.addNamespaceDeclaration("soapenv", soapenv);
   envelope.addNamespaceDeclaration("open", open);
   envelope.addNamespaceDeclaration("ord", ord);
   envelope.addNamespaceDeclaration("ord1", ord1);
   envelope.addNamespaceDeclaration("com", com);
   envelope.addNamespaceDeclaration("wsse", wsse);
   envelope.addNamespaceDeclaration("wsu", wsu);
   SOAPHeader soapheader = envelope.getHeader();SOAPBody soapbody = envelope.getBody();

6. Because MSS Web Services are secured, you must pass proper credentials which update the security header.

   SOAPElement soapsecurity = soapheader.addChildElement("Security","wsse");
   QName soapsecurityattribute = new QName("soapenv:mustUnderstand");
   soapsecurity.addAttribute(soapsecurityattribute, "1");
   
   SOAPElement soapusernametoken =
         soapsecurity.addChildElement("UsernameToken","wsse");
   QName usernameattribute = new QName("wsu:Id");
   soapusernametoken.addAttribute(usernameattribute,
         "UsernameToken-983A273E3EDA90F960148681422777119");
   
   SOAPElement soapusername =
         soapusernametoken.addChildElement("Username","wsse");
   soapusername.addTextNode("yourUsername");
   SOAPElement soappassword =
         soapusernametoken.addChildElement("Password","wsse");
   QName passwordattribute = new QName("Type");
   soappassword.addAttribute(passwordattribute,
      "http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText");
   /* password is your password value set in the addTextNode method */
   soappassword.addTextNode("password");

7. Add the contents to the message body.

   /* Add the SOAP body */
   SOAPElement soapgetOrder = soapbody.addChildElement("getOrderByKey", "open");
   SOAPElement soapmomGetOrderByKeyRequest =
         soapgetOrder.addChildElement("momGetOrderByKeyRequest", "ord");
   SOAPElement soapmommekey =
         soapmomGetOrderByKeyRequest.addChildElement("mommekey","ord");
   SOAPElement soapmetaSolvOrderKey =
         soapmommekey.addChildElement("metaSolvOrderKey","ord1");
   SOAPElement soapapplicationDN =
         soapmetaSolvOrderKey.addChildElement("applicationDN","com");
   SOAPElement soaptype = soapmetaSolvOrderKey.addChildElement("type","com");
   SOAPElement soapprimaryKey =
         soapmetaSolvOrderKey.addChildElement("primaryKey","ord1");
   /* This DOCUMENT_NUMBER is for the order number */
   soapprimaryKey.addTextNode(DOCUMENT_NUMBER);

8. Add the code to invoke the web service. The soapResponse variable contains the output details.

   /* Call with the SOAP message being returned */
   SOAPMessage soapResponse = con.call(message, url);

In using the XML APIs a subordinate or child structure may be returned with empty data. In using the MSS Web Services, subordinate structures are only returned with data for a response. For instance, if you retrieve a PSR order with a web service operation and the user data does not exist, the user data structure is not returned as part of the response.

In retrieving the Design Layout Report (DLR) details using the getServiceRequestDLRs operation, the field values for the circuit type are modified. Table 2-12 shows the before and after values for the 'type' field in the DLRResult complexType.

The ServiceActivationAPI.xsd file is removed from the schemas and is not referenced in WSDL files. The references from the ServiceActivationAPI.xsd schema file are now located in the Service.xsd schema file.