Create a Web service from a DADX file using the IBM SOAP run-time environment

Document Access Definition Extension (DADX) is an XML document format that specifies how to create a Web service using a set of operations that are defined by DAD documents and SQL statements. A DADX Web service enables you to wrap DB2 extender or regular SQL statements inside a standard Web service. The DADX file defines the operations available to the DADX run-time environment, and the input and output parameters for the SQL operation.

Use the Web services DADX Group Configuration wizard to configure your database connections. Afterwards, you create a DADX file. You can use XML tools to create DAD and DADX files. For more information on generating a DADX file from SQL, refer to Generating DADX files. You can also write DADX files using any text editor.

Then use the Web Services wizard to generate your WSDL documents, deployment descriptors, client proxy, property mappings, deployment mappings, and test your DADX Web service, in preparation for publishing your Web service to the UDDI registry.

The Web Service DADX Group Configuration wizard assists you in creating a DADX group. The DADX group contains connection (JDBC and JNDI) and other information that is shared between DADX files within the group. Once you have created a DADX group, use the Web Service wizard to assist you in creating and deploying a new Web service. Once your Web service is deployed, the wizard assists you in generating the client proxy, and sample application to test the new Web service. When you have completed testing, you can publish your Web service to a UDDI Business Registry using the Export wizard.

For more information on publishing your Web service using the Web Services Explorer, refer to Publishing a Web service.

Parent topic

Create the DADX group

In the Navigator view, select the Web project in which you want to create the DADX group.
Click File > New > Other > Web Services in order to display the various Web service wizards.
Select the Web Services DADX Group Configuration wizard. Click Next
Select your Web project. Click Add group. Enter a name for your DADX group. Click OK.
Expand your Web project to display your DADX group. Right-click your DADX group. Select Group Properties. Change the DB URL to jdbc:db2: DATABASE_NAME where DATABASE_NAME is the name of your database. Enter the user ID and password for a user with authority to access the database. Enter any additionally required parameters:

Context Factory

When using a datasource to connect to the database this value specifies the context factory class that should be used. The suggested value when running on a WebSphere server is com.ibm.websphere.naming.WsnInitialContextFactory.

Datasource

When using a datasource to connect to the database this value specifies the datasource name to be used.

DB driver

When using JDBC to connect to the database this value specifies the database driver class to be used.

DB URL

When using JDBC to connect to the database this value specifies the database URL of the database.

Userid and Password

These fields are used to specify the authentication information when connecting either via a datasource or by JDBC.

Namespacetable

The field specifies the namespace table file name that the DADX runtime should use. This file defines mapping between DTD identifiers and their associated XSD namespace and location. Note: entries in this file only need to be made if the DADX file references a DAD file.

Autoreload

This field specifies whether the DADX runtime should reload resources, such as a DADX file, that have changed on the server.

Reload interval

This value specifies in seconds how often the DADX runtime should check for changed resources. Note: this is only used if autoreload is set to true.

Group namespace URI

This field specifies the namespace URI prefix that is put at the beginning of all namespaces associated with DADX files in this DADX group. If this field is left blank the default prefix is http://tempuri.org.

Enable XML CLOB

This field specifies with the DB2 XML Extender CLOB feature should be used or not. This value should be true when using DB2 XML Extender 7.2 and later. It should be false for older versions.

Use document Style

This field indicates whether the DADX runtime should use document style or RPC style. A value of true indicates that document style should be used. Otherwise RPC style is used.

Click OK.
Click Finish. Your DADX group is generated in: WebProject\JavaSource\groups

Create a Web service from a DADX

Create or import your DADX file into your DADX group: WebProject\JavaSource\groups\ DADXGroup where DADXGroup is the group that you just created in the steps above. Important: Any relative DAD files also need to be in this folder. At run time, this is where these files will be expected to be located. If this is not true, you may experience database or server errors. For more information on DAD or creating DADX files, refer to XML tools.
Select your DADX file.
Click File > New > Other. Select Web Services in order to display the various Web service wizards. Select the Web Service wizard. Click Next.
On the Web Service page select DADX Web service from the Web service type drop down list. You can optionally choose to do the following:
- Start the Web service in a Web project - if you do not select this option you will have to manually start the Web service. You must select this option to enable the other options on this page.
- Launch the Web Services Explorer to publish your Web service to a UDDI registry.
- Generate a Java bean client proxy to the Web service. The Java bean client proxy that is generated provides a remote procedure call interface to the Web service.
- Test the Web service - this allows you to test the Web service in the Web Service Explorer before a proxy is generated.
- Send the Web service traffic through the TCP/IP Monitor, which allows you to watch the SOAP traffic generated by the Web service and to test this traffic for WS-I compliance.
Service Deployment Configuration page: specify the server and client deployment settings.
1. Click Edit and select the IBM SOAP run-time environment and select the server on which you want to run your Web service and Web service client.
2. Accept the default Web project and EAR in which you want your Web service created. Ensure that the project selected contains the DADX group which contains the DADX file. The wizard will create these for you if they do not already exist. Note: You must accept the default project names or the wizard may not be able to proceed.
3. Accept the type and name of project in which you want the Web service client created. Note: You must accept the default project names or the wizard may not be able to proceed.
4. Select an existing EAR or enter a unique name to associate the Web service client with a different EAR than the Web service EAR. Note: Selecting different EARs for the Web service and Web service client can reduce the chance of encountering run time errors, but will use more system resources.
Web Service DADX File Selection Page: Enter the name of the DADX file from which you want to create a Web service.
Web Service Binding Proxy Generation panel: if you have selected to generate a proxy, select the binding and proxy options.
Web Service Client Test page: Use this page to select the following options:
- Select your test facility. You can test the generated proxy in the Universal Test Client or the Web Service Explorer, or you can generate a sample Web service JSP.
- If you selected to test the proxy through a JSP, you can select the folder where the JSP will be located, and you can select the methods that will be included in the JSP.
- Select Run test on server to start the server for you automatically.
Web Service Publication page: Select whether or not you want to publish this Web service to a UDDI registry. Click Finish.
After the Web service has been created, the following may occur depending on the options you selected:
- If you have selected to test the generated proxy using Web service JSPs, the proxy is launched in a Web browser at the following URL: http://localhost: port/WebProjectClient/sampleBeanName/ WebService/TestClient.jsp You can use this sample application to test the Web service by selecting a method, entering a value for the method, and clicking Invoke. The result of the method will display in the results pane.
- If you have selected to test the generated proxy using the Universal Test Client, it will be launched in a browser window at the following URL: http://localhost:9080/UTC/preload?object=proxy.soap. ProxyNameProxy In the Reference pane, under Object References, expand the proxy to display the methods of the Web service. Click the method you want to test, enter a value in the Parameters pane, and click Invoke. The result will be generated below.
- If you have selected to test the Web service using the Web Services Explorer, the Explorer will open. Select the operation you want to test, enter the required information, and click Go. The result will display in the Status pane.
- If you have selected to publish the Web service, the Web Services Explorer is launched displaying the page required to publish your Web service to the IBM UDDI Test Registry. Follow the instructions in Publishing the Web service to complete this task.

For more information on DB2 XML Extender and the DADX specification, refer to www.ibm.com/software/data/db2/extenders/xmlext/library.html

If you are running DADX on a remote server, manually copy worf.jar from the plugins/com.ibm.etools.webservice.consumption.soap_version/runtime folder to somewhere on your remote machine. You must then update the classpath of the remote server to reference this worf.jar file.

Important:

DADX Web services frequently return complex types that the generated sample application cannot handle. To test the methods that return DOM Elements, invoke the DOM Element methods of the proxy instead of the Java bean methods of the proxy.
You cannot mix SOAP encoding and literal encoding for RPC style messages in a WSDL file being used to generate a WebSphere 5.1 or Apache Axis client. Therefore, a WebSphere v51 or Apache Axis client can not be properly created from a WSDL file which was generated for a DADX Web service that uses RPC. To prevent this, create the DADX Web service using DOC style. The v5.1 WebSphere run-time can create a client from this WSDL without a problem. To use DOC style DADX Web services, set the useDocumentStyle parameter in the group.properties file for the DADX group to true. This can also be done through the DADX group configuration wizard.
In order to improve interoperability with Microsoft Web services, the DADX runtime can now generate document style Web services. To enable this feature, use the DADX configuration wizard to open the property page for a DADX group that is to be used. At the bottom of the property page ensure that the "Use document style" entry field is set to true.
The DADX schema no longer uses the WSDL document tag for documentation. This tag is now a part of the DADX schema. This may cause validation problems with old DADX files that have not been migrated to using the updated schema. For example, if your old DADX file contained the following XML:
<wsdl:documentation xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"> Provides queries for part order information at myco.com. </wsdl:documentation>

the new document entry would be:

<documentation> Provides queries for part order information at myco.com. </documentation>
If your methods contain types, not supported by samples, such as arrays, indexed properties, and collections, the methods will be omitted from the sample and you will receive a warning message.
Stored procedure parameters can not contain underscores when the stored procedure is used to create a DADX Web service. For example, a Java stored procedure might look like this:
```
 public static void test ( String class_code,
                           short day,
                           java.sql.Time starting,
                           java.sql.Time ending ) throws SQLException, Exception
```
In this case the class_code parameter would cause the DADX runtime to fail. To avoid this problem use a parameter name without an underscore.
Ensure that the DADX file that you select to turn into a Web service is contained in the WebProject\JavaSource\groups\ DADXgroup directory. Any relative DAD files also need to be in this folder. At run time, this is where these files will be expected to be located. If this is not true, you may experience database or server errors.
You can use the DADX File wizard to generate a DADX file into the DADXGroup folder. For more information on creating a DADX file, refer to XML tools.
Normally multiple outputs in a Web service is not supported. However, DADX Web services support multiple outputs if the use document Style group property is set to true. In this case, multiple outputs are combined into a single XML document.
In a DADX group you can specify a JDBC net driver. For DB2 the net driver class is COM.ibm.db2.jdbc.net.DB2Driver. For earlier versions of DB2, db2java.zip needed to be added to the server classpath, and this zip file contains the driver. However, with DB2 version 8.1 and later, the file db2jcc.jar also needs to be added to the server classpath. The file is usually located in the same directory as the db2java.zip file. Ensure that The DB2 client level on your machine is at the same fixpack level as the DB2 server that you are connecting to.

Related Concepts

Tools for Web services development
Web services development
Web services run-time environments

Creating a Web service from a DADX file using the IBM SOAP run-time environment

Parent topic

Create the DADX group

Create a Web service from a DADX

Related Concepts