Skip navigation.
Downloads | Product Documentation | Support

Client Application Developer's Guide

# Web Services and DSP-Enabled Applications

Web services provide an industry-standard way to develop SOA (service-oriented architecture) applications—loosely coupled, distributed units of programming logic that can be re-configured easily to deliver new application functionality, both intra- and extra-enterprise. By wrapping your data services as Web services, you enhance the Web services model with a data services layer that can abstract a wide variety of data sources, including relational database management systems, workflow applications, portals, and other Web services.

In short, using Web services and BEA AquaLogic Data Services Platform (DSP) together lets you leverage all your data assets. This chapter shows you how to expose data services as standard Web services, and how to create client applications that can obtain the benefits of both Web services and SDOs. It covers these topics:

- Overview of Web Services and DSP
- Server-side DSP-Enabled Web Service Development
- Client-side DSP-Enabled Web Service Development

# Overview of Web Services and DSP

Exposing data services as Web services makes your information assets accessible to a wide variety of client types, including other Java Web service clients, Microsoft ADO.NET and other non-Java applications, and other Web services (see Figure 4-1).

Figure 4-1 Web Services Enables Access to DSP-Enabled Applications from a Variety of Clients

Figure 4-1 illustrates the various approaches that client application developers can take to integrating data services and Web services.

Note: This chapter focuses on leveraging DSP-enabled applications as Web services, and on accessing such DSP-enabled Web services from Java client applications. For information about ADO.NET-enabled Web services and client applications, see Supporting ADO.NET Clients.

## Different Styles of Web Services Integration for DSP

DSP-enabled applications can be integrated with Web services in one of two general ways:

- As a standard Web service. A standard Web service can be invoked from other Web services, or by .NET clients or any other type of client, Java and non-Java alike. On the server side, at runtime, the Web service simply passes the results obtained from the data service function back to the client as a standard SOAP message. This approach is best for simple query only applications that do not need to modify or add data to back-end data sources behind the Web service facade.
- As an SDO-Enabled Web service. An SDO-enabled Web service can support updates to back-end data sources. You can use either static SDOs client-side proxy code (as detailed Generating SDO-Enabled Web Services Clients on page 4-18), or use dynamic SDOs (also known as generic SDO), which are automatically downloaded to the client at runtime.

Note: For details on working with static and dynamic SDO see Static and Dynamic SDO APIs.

This chapter covers SDO-enabled Web service client applications, starting with the server-side development tasks required to expose DSP-enabled applications as Web services. Figure 4-2 shows the end-to-end process—both the server-side and client-side tasks—that expose a DSP-enabled application as a Web service and implement a client application that invokes operations on that service.

Figure 4-2 Java Clients Supported via Web Services

# Server-side DSP-Enabled Web Service Development

There are two ways to easily integrate data services with Web services:

- Adding a Data Service Control to a Web Service
- Generating a Web Service from a Data Service Control

Both approaches, covered in the next two sections, rely on Data Service controls as the component-based integration mechanism.

## Adding a Data Service Control to a Web Service

You can easily add one or more Data Service controls to a Web service using WebLogic Workshop. You must first create a folder for the controls inside the Web service's project folder, and then create the Data Service controls. The controls must be placed inside the controls folder so they will be available to add to the Web service, as instructed in this section.

Note: You can also create controls during the process of adding them to the Web service, but for simplicity's sake, the instructions in this section assume that you have created the Data Service controls in advance. (See Creating Data Service Controls for more information about creating Data Service controls.)

1. In WebLogic Workshop, open the existing Web service file (JWS) by double-clicking on its name in the Application pane.
2. Click the Design View tab on the Web service to open the graphical representation of the Web service (as shown in Figure 4-3).

Figure 4-3 Adding a Data Service Control to a Web Service

3. Right-click and select Add Control —> Data Service from the popup menu. The Insert Control - Data Service wizard launches, showing the multi-step dialog page shown in Figure 4-4.
4. In the STEP 1 field of the dialog, enter a meaningful variable name for the Data Service control that is unique in the context of the Web service.

Figure 4-4 Insert Control - Data Services Wizard

5. In the STEP 2 field, click Browse... to navigate to the controls folder, then select the Data Service control you want to add to the Web service. (Alternatively, click Create a New Data Service Control button to launch the Data Service control wizard to create and configure a new control.)

Leave the Make This a Control Factory checkbox de-selected: This checkbox will cause the Data Service control to be instantiated at runtime using the factory pattern, rather than as a singleton. To use the control in a Web service, it must be a singleton.

6. In the STEP 3 section of the dialog (which will be active only if your Data Service control is associated with a remote DSP instance, that is, a DSP instance running on a separate domain from WebLogic Workshop), provide the user name, password, server URL, and domain information associated with the remote Data Service control to complete the link between the Web service and the control.
7. Click the Create button on the Insert Control - Data Service dialog. The `LiquidDataControl.jar` file is copied into the Libraries directory of the application, and the variable you created in STEP 1 of the dialog displays as a node in the Data Palette, with its functions and procedures listed under the node. It is these functions and procedures that you can now expose to client applications, by adding them to the Web service's callable interface (shown as the left-hand portion of the Web service's Design View in WebLogic Workshop — see Figure 4-5), as described in the next step.

Figure 4-5 Adding Functions from a Data Service Control to a Web Service

8. Select the function or procedure from under the variable name listed in the Data Palette by clicking on the node, and then drag and drop the function onto the left side of the Web service in Design View.

When you are finished, you can test the Web service as described in Testing a Web Service in WebLogic Workshop. After testing, you can deploy to your production WebLogic Server and use it as you would any other Web service. For more information about Web services, see:

http://e-docs.bea.com/wls/docs81/webservices.html

For information about developing Java-based Web service clients, see Client-side DSP-Enabled Web Service Development.

## Generating a Web Service from a Data Service Control

Using WebLogic Workshop you can generate stateful or stateless (conversational) Web services from Data Service controls. The generated Web services include method calls (referred to as operations) for each of the functions and procedures that the Data Service control comprises, as well as two operations specifically for testing the Web service.

Follow the instructions in this section to generate and test a stateless Web service. The instructions assume that you have already created the Data Service control and that WebLogic Workshop is open.

Figure 4-6 Stateless Web Services Are Generated from Data Service Controls

1. From WebLogic Workshop's Application pane, select the Data Service control that you want to use as the basis for your Web service by clicking on its name. While the control is selected, right-mouse-click to display the pop-up menu; select Generate Test JWS File (Stateless) from the menu. WebLogic Workshop generates the JWS Java Web service file for your Data Service control.

Note: Note that although WebLogic Workshop by default generates Web services that have the word "Test" embedded in the file names, these are deployable Web services. You can rename the generated Web service to eliminate the word "Test" from its name.

1. Click on your Web service project to select it, right-click, and select Build Project. WebLogic Workshop builds a Web service project.
2. When the build process completes, double-click on the `.jws` file to open it. Click the Design View tab if necessary to display the generated Web service in the Design View.

You will see methods (operations) for each of the functions and procedures contained in the Data Service control, as well as two additional operations, startTestDrive() and finishTestDrive(). You can use these two operations to quickly test the Web service (using WebLogic Workshop's runtime server), as described in Testing a Web Service in WebLogic Workshop. Before testing, however, you should modify any submit() operations in your generated Java Web service, as described in the next section.

### Modifying Submit Operations and Generating a WSDL File

If the Web service must support submits from Java Web service clients, you must modify the JWS file before generating the WSDL, as follows:

1. Modify submit operations in your Java Web service (JWS) implementation control file to accept a DatagraphDocument object as a parameter. The signature for the submit() method should be similar to:

>     java.util.Properties[] submitCustomerProfile(DatagraphDocument
>      rootDataObject)

2. Modify the body of the submit operation to instantiate and initialize the document from a DatagraphDocument object being passed as a parameter; for example:

>     CustomerProfileDocument doc = (CustomerProfileDocument) new    DataGraphImpl(rootDataObject).getRootObject();
>     return customerData.submitCustomerProfile(doc);

The following code shows the context of a method declaration.

>     public java.util.Properties[] submitCustomerProfile(DatagraphDocument   rootDataObject) throws Exception {
>     CustomerProfileDocument doc = (CustomerProfileDocument) new DataGraphImpl(
>                         rootDataObject).getRootObject();
>     return customerData.submitCustomerProfile(doc);
>     }

1. Generate a Web Service Definition Language (WSDL) file from the JWS file by right-clicking on on the file name and selecting the Generate WSDL file option.

After you have created the WSDL file, provide it to client application developers, so they can generate the Web services client interfaces and proxy code necessary (as discussed in Client-side DSP-Enabled Web Service Development).

## Testing a Web Service in WebLogic Workshop

By default, WebLogic Workshop creates two operations in its generated Web services that can be used for testing purposes.

1. Click the Start icon (or select Debug —> Start from the WebLogic Workshop menu) to deploy and run the Web service using the local runtime. An informational message briefly appears, notifying you that the Web service is running. Shortly, the WebLogic Workshop Test Browser launches, displaying the Test Form, as shown in Figure 4-7.

Figure 4-7 WebLogic Workshop Test Browser

2. Click the startTestDrive button to start the conversation for the Web service.
3. Click the Continue this Conversation link (in the left corner of the test page). The available operations display as buttons on the page, along with informational messages.
4. Enter values for any query parameters (if the query has parameters) and click the button with the name corresponding to the query you want to execute. The Web service executes the query and returns results to the test browser.
5. To run the query again or run other queries in the Web service, click Continue this Conversation, enter any needed parameters and click the button with the name corresponding to the query you want to execute.
6. To end the Web service conversation, click the Continue this Conversation link (to redisplay the Test Form page) and then click the finishTestDrive button.

Continue developing the functionality of the Web service as required, testing as you go along. Once the Web service is complete, you can create the artifacts necessary for client application development, as described in the next section, Client-side DSP-Enabled Web Service Development.

Note: For more information about Web service client applications and WebLogic Server in general, see Invoking Web Services in Programming WebLogic Web Services in the WebLogic Server documentation.

# Client-side DSP-Enabled Web Service Development

There are many different approaches to developing Web service client applications, but the choices in any given instance are limited by the type of Web service itself. For example, if the Web service is an ADO.NET-Enabled Web service hosting data service functions, the assumption is that a Microsoft ADO.NET client Web service application will be using the Web service—not a Java client.

Another consideration is whether the client application will use the static or dynamic approach to Web services, as follows:

- Static Web service client. Uses typed client classes (derived from Stub base class) to invoke Web service operations on local proxy. DSP includes utilities (Java classes and Ant tasks) to generate the following code:

- SDO client classes (for typed clients)
- Web service client proxy (stub) that can instantiate and manipulate SDOs

- Dynamic Web service client. Uses Call interface from a client to dynamically invoke Web service operations. In this context dynamic means late-binding.

Either approach can be used with DSP-enabled Web service applications. Listing 4-1 shows an example of a Java Web service client application that invokes several operations on a DSP-enabled Web service. The example implements the static Web service client model, and demonstrates how to marshal data from Java for a SOAP request, by serializing an SDO DataGraph:

>     wssoap.submitCustomer(((DataGraphImpl)doc.getDataGraph()).getSerializedDocument());

At runtime, DSP uses a codec (DataGraphCodec, an encoder-decoder class that extends AbstractCodec) behind the scenes to:

- serialize SDO DataGraphs when marshalling data for SOAP requests (Java-to-SOAP)
- de-serialize SDO DataGraphs when SOAP messages are un-marshaled (SOAP-to-Java)

Listing 4-1 Sample Java Client

>     public class ClientTest {

>       public static void main(String[] args) throws Exception {

>     	SimpleCtrlTest wstest = new SimpleCtrlTest_Impl();

>     	SimpleCtrlTestSoap wssoap = wstest.getSimpleCtrlTestSoap();

>     	CUSTOMERDocument doc = wssoap.getCustomer(987654);

>     	doc.getCUSTOMER().setCUSTOMERNAME("323777");

>     	String result = doc.getDataGraph().toString();

>     	System.out.println(result);

>     wssoap.submitCustomer(((DataGraphImpl)doc.getDataGraph()).ge	tSerializedDocument());

}

Data Services Platform automatically downloads the typed client-side artifacts upon first invocation of a Web service operation, as required.

## Client-side Artifact Generation Utilities

Data Services Platform provides both Ant tasks and Java classes for generating the various artifacts required for DSP-enabled Web service client development (see Table 4-8). The Ant tasks can be thought of as wrappers around the Java classes to which they refer, and provide a simple way to incorporate the Java classes into an Ant build script.

Table 4-8 DSP's Web Service Client Utilities Summary

####

Utility | Description | Classname
--- | --- | ---
sdogen | Ant task that compiles client SDO classes1 from XSD or WSDL files. | `com.bea.sdo.impl.SDOGenTask`
sdoclientgen | Ant task that generates Web service-specific client proxy (stub classes) from a DSP-enabled Web service's WSDL. | `com.bea.sdo.impl.WSClientGenTask`
SDOGen | Java class that generates typed client SDO classes. | `com.bea.sdo.impl.SDOGen`
WSClientGen | Java class that generates typed Web service client proxy (stub classes). | `com.bea.sdo.impl.WSClientGen`

1. <appname>-ld-client.jar

## Generating SDO Client Classes

Developing a Web services client application that can access and update SDOs hosted on a Web service requires one of the following:

- Access to the Web service (through its URL, over the network; through UDDI, if the Web service is registered in a public or private UDDI registry; or by access to the physical WSDL file, located locally on the development machine.)
- Access to the XML schema definition (XSD) files that comprise the data type definitions for the data service.

DSP provides an Ant task and a Java application, each of which can use either the WSDL or XSD to generate the client side artifacts.

### Setting the Environment for the Utilities

1. At a command prompt, navigate to the directory where the build script and Ant configuration file are located:

>     <bea_home>\weblogic81\samples\domains\ldplatform

2. Execute the shell or command file script to set the environment for your machine (Windows or Unix):

>     setDomainEnv.cmd

>     setDomainEnv.sh

### Generating SDO Classes Using Ant

The SDOGen Ant task creates an SDO client JAR file that contains the typed classes for working with SDOs. It can use either the XSDs from the data service or the WSDL (assuming the DSP-enabled application has been exposed as a Web service) to generate the SDO classes and compile them into the client JAR file.

The SDOGen Ant task lets you build the necessary SDO client JAR which you can then use in your client application code. You can also run the SDOGen task so that it generates the Java and XML (XMLBeans) source code that comprises the SDO type system specified by the schema files.

#### Environmental Settings

To generate the classes, make sure your classpath includes:

- `wlsdo.jar`
- `xbean.jar`

#### Syntax

To create a JAR comprising the client classes, execute sdogen at the command prompt as follows:

1. Add the sdogen taskdef to the build script. For example:

>     <taskdef name="sdogen" classname="com.bea.sdo.impl.SDOGenTask" classpath="path/to/wlsdo.jar:path/to/xbean.jar"/>

This task implicitly defines an Ant FileSet, and supports all FileSet attributes (for example, dir becomes basedir) as well as the nested attributes and elements.

Table 4-9 summarizes the attributes used by the sdogen Ant task.

Table 4-9 Attributes Available for DSP's SDO Generation (sdogen) Ant Task

####

Attribute | Description | Required? | Default Value
--- | --- | --- | ---
`schema` | A file that points to either an individual schema file or a directory of files. Not a path reference. If multiple schema files need to be built together, use a nested fileset instead of setting schema. | Yes | None
`destfile` | Creates a non-default name for the JAR file. For instance, myXMLBean.jar will output the results of this task into a JAR named myXMLBean. | No | xmltypes.jar
`classgendir` | Directory in which to generate .class files. | No | Current directory
`classpath` | Specify the classpath if Java files are in the schema fileset, or if the fileset imports include compiled XMLBeans JAR files. Also supports a nested classpath. | No |
`classpathref` | Adds a classpath, given as reference to a path defined elsewhere. | No |
`debug` | Indicates whether source should be compiled with debug information. If set to false (off), -g:none will be passed on the command line for compilers that support it (for other compilers, no command line argument will be used). If set to true, the value of the debuglevel attribute determines the command line argument. | No | False (off)
`fork` | Flag that indicates whether the JDK compiler (javac) should be executed externally. | No | Yes
`memoryInitialSize` | The initial size of the memory for the underlying VM, if javac is run externally; ignored otherwise. Defaults to the standard VM memory setting. | No | Configured VM memory setting for the machine. For example: 83886080, 81920k, or 80m.
`memoryMaximumSize` | The maximum size of the memory for the underlying VM, if javac is run externally; ignored otherwise. Defaults to the standard VM memory setting. | No | Configured VM memory setting for the machine. For example: 83886080, 81920k, or 80m.
`verbose` | Controls the amount of build message output. | No | True

To build all XML schema definition (XSD) files in the schemas directory and create a JAR named `Schemas.jar`, your Ant script would include the following:

>     <sdogen schema="MyTestWS.WSDL" destfile="Schemas.jar" classpath="path/to/wlsdo.jar:path/to/xbean.jar"/>

### Generating SDO Classes Using Java

Rather than using the SDOGen Ant task, you can use the SDOGen Java class at the command-line to generate SDO client classes.

from XML schema definition (XSD) files or WSDL files based on data services.

SDOGen is a Java class that extends the XMLBean schema compiler class.

Optionally, by using the -srconly parameter, the utility can provide you with generated Java source files that define the classes, prior to compiling. Using the -srconly parameter, for example, you can generate the sources and then from the sources, generate Javadoc. In this way you can examine the class hierarchy and methods of the XML data type handlers.

See Table 4-12 for other command-line options for the SDOGen utility.

Table 4-10 Command-line Options for the Java SDO Class Generation Utility

####

Option | Description | Default Value
--- | --- | ---
`-cp [a;b;c]` | Classpath |
`-d [dir]` | Target directory for binary `.class` and `.xsb` files. |
`-src [dir]` | Target directory for generated Java source files. |
`-srconly` | Flag to prevent compiling Java source files and archiving into JAR file. |
`-out [result.jar]` | Name of the output JAR file. | `xmltype.jar`
`-dl` | Enables network downloads for imports and includes. | Off (not enabled).
`-noupa` | Do not enforce the unique particle attribution rule. |
`-nopvr` | Do not enforce the particle valid (restriction) rule |
`-compiler` | Path to external Java compiler. |
`-jar` | Path to JAR (Java Archive) utility |
`-ms` | Initial memory for external Java compiler | 8 Megabyte
`-mx` | Maximum memory for external Java compiler | 256 Megabyte
`-debug` | Compile with debug symbols. |
`-quiet` | Print minimal informational messages to Java console. |
`-verbose` | Print maximum amount of informational messages to Java console. |
`-license` | Prints license information. |
`-allowmdef "[ns] [ns] [ns]"` | Ignores multiple defs in given namespaces. |

#### Environmental Settings

To execute the utility, make sure your classpath includes:

- `wlsdo.jar`
- `xbean.jar`

#### Syntax

To create a JAR comprising the client classes, execute SDOGen at the command prompt as follows:

>     java com.bea.sdo.impl.SDOGen [options] xmlschema

XMLSchema can be:

- the URL of a WSDL
- an XSD or WSDL file
- a directory containing numerous XSD or WSDL files

#### Usage Examples

The following are examples of using SDOGen with various options (see Table 4-10) to obtain different results:

- To create a file named xmltype.jar (the default) based on the WSDL associated with Web service named MyApp running locally:

>     java com.bea.sdo.impl.SDOGen http://localhost:7001/WebApp/DSCtrls/MyApp.jws?WSDL

- To create a file named xmltype.jar (the default) based on the WSDL associated with a publicly available Web service. (The -dl option permits downloading.):

>     java com.bea.sdo.impl.SDOGen -dl http://198.68.125.17:7001/WebApp/DSCtrls/MyApp.jws?WSDL

- To create a file named xmltype.jar using XML schema definition (XSD files) located in the `\myApps\xsd_dir` directory on the local machine:

>     java com.bea.sdo.impl.SDOGen C:\myApps\xsd_dir

- To create the MySDOClasses.jar file in the `c:\test\xsd_dir` directory:

>     java com.bea.sdo.impl.SDOGen -out MySDOClasses.jar C:\test\xsd_dir

## Generating SDO-Enabled Web Services Clients

SDO Web service client generation can be done using the Ant task (SDO Web Service Client Gen) or the Java class (WSClientGen).

### Generating SDO Web Services Clients Using Ant

The SDO Web Service Client Gen utility is an Ant task generates an SDO-enabled Web services client JAR file that client applications can use to consume JWS generated from a Data Service control. The generated client JAR file includes:

- Client interface and stub files (conforming to the JAX-RPC specification) used to invoke a Web service in static mode.
- Optional serialization class for converting SDO classes between its XML and Java representation.
- Optional client-side copy of the Web service WSDL file.

Although you could use the SDO Ant task to generate a client JAR file from the WSDL file of any existing Web service (not necessarily running on WebLogic Server), the SDO Client Gen utility typically is used to generate the JAR file from an existing WSDL file of an SDO-enabled JWS.

The WebLogic Server distribution includes a client runtime JAR file (webserviceclient.jar) that contains the client side classes needed to support the WebLogic Web services runtime component.

#### Environmental Settings

Environmental settings must include the following JAR files from `weblogic/server/lib`:

- `xbean.jar`
- `wlxbean.jar`
- `xqrl.jar`
- `webservices.jar`

You also must include `wlsdo.jar` from the `liquiddata/lib` folder.

#### Syntax

Define your Ant task for SDOClientGen as follows:

>     <taskdef name="sdoclientgen" classname="com.bea.sdo.impl.WSClientGenTask" classpath="path/to/SDOclasses:path/to/wlsdo.jar:path/to/xbean.jar:path/to/wlxbean.jar:path/to/xqrl.jar:path/to/webservices.jar"/>

#### Usage Examples

>     <sdoclientgen wsdl="http://example.com/myapp/myservice.wsdl" packageName="sdoclient" clientJar="myapps/mySDO_WSclient.jar" classpathref="all the JAR files listed in the task"/>

Table 4-11 Attributes Available for DSP's Web-Services Client Proxy Code Generation Ant Task

####

Attribute | Description | Required?
--- | --- | ---
`packageName` | Package name for the generated JAX-RPC client interfaces and stub files. | Yes
`wsdl` | Full path name or URL of the WSDL that describes a Web service (either WebLogic or non-WebLogic) for which a client JAR file should be generated. The generated stub factory classes in the client JAR file use the value of this attribute in the default constructor. | Yes
`clientJar` | Name of a JAR file or exploded directory into which the clientgen task puts the generated client interface classes, stub classes, optional serialization class, and so on. To create or update a JAR file, speechify the fullname, including the JAR extension (`myclient.jar`); otherwise, the clientgen task interprets the name as a directory. If the specified JAR or directory does not exist, the clientgen task creates a new JAR file or directory. | No
`classpath` | Must include the path to the SDO classes generated from the XSD or WSDL by the SDOGen Ant task. | No
`classpathref` | Adds a classpath, given as reference to a path defined elsewhere. | No

### Generating SDO Web Services Clients using Java

The Web Services Client Generation utility is a Java class (WSClientGen) that developers can use to generate Web services client interfaces and stub classes from a WSDL that uses typed SDO classes for argument and return types. Use this utility to create the artifacts necessary for a client application to invoke DSP functions or submit SDOs.

#### Environmental Settings

Environmental settings must include the following JAR files from `weblogic/server/lib`:

- `xbean.jar`
- `wlxbean.jar`
- `xqrl.jar`
- `webservices.jar`

You also must include `wlsdo.jar` from the `liquiddata/lib` folder.

#### Syntax

Define your Ant task for SDOClientGen as follows:

>     <taskdef name="sdoclientgen" classname="com.bea.sdo.impl.WSClientGenTask" classpath="path/to/SDOclasses:path/to/wlsdo.jar:path/to/xbean.jar:path/to/wlxbean.jar:path/to/xqrl.jar:path/to/webservices.jar"/>

The following should also be kept in mind:

- Make sure the Web service is running if you want to obtain the WSDL by using the Web service's URL.
- Use the SDOGen utility to first generate the JAR file (of typed SDO classes) from the DSP-enabled Web service's WSDL.
- Execute the Java utility as follows:

>     java com.bea.sdo.impl.WSClientGen [options] wsdl

The WSDL can be the URL of the WSDL (available over the network), or the actual, physical WSDL file located on your machine. Command-line options that you can pass to the utility are shown in Table 4-12.

#### Usage Examples

Here are some examples of using the utility:

- To generate an SDO client JAR file from a publicly available WSDL, pass the URL to the Web service as an argument on the command line:

>     java com.bea.sdo.impl.WSClientGen http://localhost:7001/WebApp/DSCtrls/MyApp.jws?WSDL

- To create a JAR named MyClient.jar (rather than the default), pass the filename with the -clientJar parameter at the command line:

>     java com.bea.sdo.impl.WSClientGen -clientJar MyClient.jar http://localhost:7001/WebApp/DSCtrls/MyApp.jws?WSDL

Table 4-12 WSClientGen Utility Options

####

Option | Description | Default Value
--- | --- | ---
`-version` | Print version information to the Java console. |
`-verbose` | Print the maximum amount of informational messages to the Java console. |
`-clientJar` | Specify the name for the generated JAR file. | `SDOClient.jar`
`-packageName` | Package name of the generated JAX-RPC client interfaces and stub. | sdoclient
`-overwrite` | Boolean that specifies if existing files should be overwritten by newly generated code. | True
`-keepGenerated` | Boolean that specifies if generated Java source code should be deleted (False) or kept (True). | False

### Using the SDO Web Service Client Gen Utility

The SDO Web Service Client Gen utility is an Ant build script that you can invoked from a command line to build SDO objects for the client. The script (including its pathname) is:

>     <bea_home>\weblogic81\liquiddata\bin\sdo_wsclientgen.xml

The WSDL file you created in the procedure described in Modifying Submit Operations and Generating a WSDL File is passed to the utility as a parameter, and the SDO objects generated by `sdo_wsclientgen.xml` are based on that file.

The configuration parameters for the Ant build script `sdo_wsclientgen.xml` are:

- clientJar`.` The name of the JAR file that will be created.
- wsdl. The full path to the WSDL file needed to create the SDO objects.
- classgendir. The path to location of the generated JAR file.

Before using the Ant script to build SDO classes, make sure you set your environment by calling the setWLSEnv.cmd in the command prompt window. This command file is located in the directory $bea_home\weblogic81\server\bin.

You must include the following packages in your client's CLASSPATH to work with SDO objects:

- `wlsdo.jar`
- `webserviceclient.jar`
- `xbean.jar`
- `wlxbean.jar`
- `xqrl.jar`
- Generated SDO WS client JAR file. The generated SDO WS client JAR file is the file you produced in step 3 of the procedure described in "Modifying Submit Operations and Generating a WSDL File."

The specific steps you need to perform with the Ant utility in order to build SDO classes are:

1. Set the domain environment. For example:

>     \bea\weblogic81\samples\domains\ldplatform\setDomainEnv.cmd

2. Set the WebLogic environment. For example:

>     \bea\weblogic81\server\bin\setWLSEnv.cmd

3. Add the sdotemp directory to the classpath:

>     set CLASSPATH=%CLASSPATH%;sdotemp

4. Call Ant from the command line:

>     ant -buildfile ./sdo_wsclientgen.xml

After using the Ant utility (that is by issuing the command, `ant sdo_wsclientget.xml`), a JAR file is created; among other generated artifacts, the JAR file contains the typed SDO classes. You can distribute the JAR files to all clients that will consume operations from this Web service.

After running the Ant utility, you can call the modified submit operation that you created in step 2 of the procedure described in Modifying Submit Operations and Generating a WSDL File. For example, your client code would be as follows, based on the submitCustomerProfile( ) method shown in step 2:

Listing 4-2 Example of Invoking the Submit Method

>     CustomerDataTestSoap wssoap = new CustomerDataTest_Impl().getCustomerDataTestSoap();
>     CustomerProfileDocument doc = wssoap.getCustomerProfile(customer_id);
>     doc.getCustomerProfile().getCustomerArray(0).setLastName("Test");
>     DataGraphImpl dg = (DataGraphImpl) doc.getDataGraph();
>     wssoap.submitCustomerProfile(dg.getSerializedDocument());

## Post-Generation Development Tasks

BEA AquaLogic Data Services Platform includes a sample Web service project — SampleWS — which is used in this section to demonstrate how to update a data service that has been wrapped as a Web service. The assumption is that the client-side programming will use the Web service's WSDL. Using the SampleWS as a starting point, you can

The procedure below adds:

- An SDO client JAR file to the library of the project
- An additional Java file that demonstrates the implementation of a modified submit method as described in "How to Update a Data Service Exposed as a Web Service."

To work with SampleWS and run the example code, do the following:

1. Import the project files for SampleWS into WebLogic Workshop by right-clicking on your Evaluation application and importing SampleWS as a Web service project. SampleWS is located in the directory:

>     $bea_home\weblogic81\samples\LiquidData\EvalGuide

2. Build your SampleWS project.
3. Right click on your application library folder and select Add Library....
4. Navigate to the following directory:

>     $bea_home\weblogic81\samples\LiquidData\EvalGuidedirectory

5. Select the `SDOClient.jar` file to be added. Click the Open button.
6. Verify that `SDOClient.jar` is imported into your library folder.
7. Right-click on your application and import ConsumeWS as a Java project. ConsumeWS is located in the directory:

>     $bea_home\weblogic81\samples\LiquidData\EvalGuide

8. Open the `ConsumeWS.java` file located in the ConsumeWS project and execute it. After executing `ConsumeWS. java`, you should see results similar to the following.

## Sample build.xml File

Listing 4-3 shows a complete example of using the Ant tasks as part of a build process.

Listing 4-3 Sample build.xml File for the SDOGen and WSClientGen Ant Tasks

>     - <project name="samplesdogen" default="build" basedir=".">
>        <property name="output.jar" value="MyTestClient.jar" />
>        <property name="wsdl.file" value="../SimpleCtrlTest.wsdl" />
>        <property name="local.build.dir" value="build" />
>        <property name="external.resource.dir" value="../DSP/external" />
>       <mkdir dir="${local.build.dir}" />
>     - <path id="compile.classpath">
>        <pathelement path="${java.class.path}" />
>        <pathelement path="${local.build.dir}" />
>        <pathelement location="${external.resource.dir}/weblogic.jar" />
>        <pathelement location="${external.resource.dir}/xbean.jar" />
>        <pathelement location="${external.resource.dir}/wlxbean.jar" />
>        <pathelement location="${external.resource.dir}/xqrl.jar" />
>        <pathelement location="${external.resource.dir}/webservices.jar" />
>        <pathelement location="${external.resource.dir}
>                      /../src/ld-core/sdoUpdate/dist/wlsdo.jar" />
>        </path>
>     <taskdef name="sdogen" classname="com.bea.sdo.impl.SDOGenTask" classpathref="compile.classpath" />
>     <taskdef name="sdoclientgen" classname="com.bea.sdo.impl.WSClientGenTask" classpathref="compile.classpath" />
>     - <target name="sdo" depends="clean">

>       <sdogen classgendir="${local.build.dir}" schema="${wsdl.file}" classpath="${external.resource.dir}/../src/ld-core/sdoUpdate/dist/wlsdo.jar:${external.resource.dir}/xbean.jar" memoryInitialSize="8m" memoryMaximumSize="256m" fork="true" failonerror="true" />
>       </target>
>     - <target name="build" depends="sdo">
>       <sdoclientgen wsdl="${wsdl.file}" packageName="sdoclient" clientJar="${local.build.dir}/${output.jar}" classpathref="compile.classpath" />
>      - <jar jarfile="${local.build.dir}/${output.jar}" update="yes">
>         - <fileset dir="${local.build.dir}">
>           <exclude name="${output.jar}" />
>           </fileset>
>         </jar>
>        </target>
>       - <target name="clean">
>           <delete dir="${local.build.dir}" />
>           <mkdir dir="${local.build.dir}" />
>        </target>
>     </project>