Client Application Developer's Guide
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
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:
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.
DSP-enabled applications can be integrated with Web services in one of two general ways:
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
There are two ways to easily integrate data services with Web services:
Both approaches, covered in the next two sections, rely on Data Service controls as the component-based integration mechanism.
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.)
Figure 4-3 Adding a Data Service Control to a Web Service
Figure 4-4 Insert Control - Data Services Wizard
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.
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
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:
For information about developing Java-based Web service clients, see Client-side DSP-Enabled Web Service Development.
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
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.
.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.
If the Web service must support submits from Java Web service clients, you must modify the JWS file before generating the WSDL, as follows:
java.util.Properties[] submitCustomerProfile(DatagraphDocument
rootDataObject)
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);
}
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).
By default, WebLogic Workshop creates two operations in its generated Web services that can be used for testing purposes.
Figure 4-7 WebLogic Workshop Test Browser
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.
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:
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:
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.
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
Ant task that compiles client SDO classes1 from XSD or WSDL files. |
||
Ant task that generates Web service-specific client proxy (stub classes) from a DSP-enabled Web service's WSDL. |
||
Java class that generates typed Web service client proxy (stub classes). |
1. <appname>-ld-client.jar |
Developing a Web services client application that can access and update SDOs hosted on a Web service requires one of the following:
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.
<bea_home>\weblogic81\samples\domains\ldplatform
setDomainEnv.cmd
setDomainEnv.sh
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.
To generate the classes, make sure your classpath includes:
To create a JAR comprising the client classes, execute sdogen at the command prompt as follows:
<taskdef name="sdogen" classname="com.bea.sdo.impl.SDOGenTask" classpath="path/to/wlsdo.jar:path/to/xbean.jar"/>
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
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"/>
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
Flag to prevent compiling Java source files and archiving into JAR file. |
||
Print maximum amount of informational messages to Java console. |
||
To execute the utility, make sure your classpath includes:
To create a JAR comprising the client classes, execute SDOGen at the command prompt as follows:
java com.bea.sdo.impl.SDOGen [options] xmlschema
The following are examples of using SDOGen with various options (see Table 4-10) to obtain different results:
java com.bea.sdo.impl.SDOGen http://localhost:7001/WebApp/DSCtrls/MyApp.jws?WSDL
java com.bea.sdo.impl.SDOGen -dl http://198.68.125.17:7001/WebApp/DSCtrls/MyApp.jws?WSDL
\myApps\xsd_dir
directory on the local machine:java com.bea.sdo.impl.SDOGen C:\myApps\xsd_dir
c:\test\xsd_dir
directory:java com.bea.sdo.impl.SDOGen -out MySDOClasses.jar C:\test\xsd_dir
SDO Web service client generation can be done using the Ant task (SDO Web Service Client Gen) or the Java class (WSClientGen).
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:
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 must include the following JAR files from weblogic/server/lib
:
You also must include wlsdo.jar
from the liquiddata/lib
folder.
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"/>
<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
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 must include the following JAR files from weblogic/server/lib
:
You also must include wlsdo.jar
from the liquiddata/lib
folder.
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:
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.
Here are some examples of using the utility:
java com.bea.sdo.impl.WSClientGen http://localhost:7001/WebApp/DSCtrls/MyApp.jws?WSDL
java com.bea.sdo.impl.WSClientGen -clientJar MyClient.jar http://localhost:7001/WebApp/DSCtrls/MyApp.jws?WSDL
Table 4-12 WSClientGen Utility Options
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:
.
The name of the JAR file that will be created.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
The specific steps you need to perform with the Ant utility in order to build SDO classes are:
\bea\weblogic81\samples\domains\ldplatform\setDomainEnv.cmd
\bea\weblogic81\server\bin\setWLSEnv.cmd
set CLASSPATH=%CLASSPATH%;sdotemp
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());
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
To work with SampleWS and run the example code, do the following:
$bea_home\weblogic81\samples\LiquidData\EvalGuide
$bea_home\weblogic81\samples\LiquidData\EvalGuidedirectory
$bea_home\weblogic81\samples\LiquidData\EvalGuide
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" />
- <target name="sdo" depends="clean">
<taskdef name="sdoclientgen" classname="com.bea.sdo.impl.WSClientGenTask" classpathref="compile.classpath" />
<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>
![]() ![]() |
![]() |
![]() |