Using UTL_DBWS to Make a Database 11g Callout to a Document Style Web Service

In this Document

Purpose

Scope

Details

---

APPLIES TO:

Oracle Database - Enterprise Edition - Version 11.1.0.6 and later
Web Services - Version 10.1.3.1.0 and later
Information in this document applies to any platform.

PURPOSE

This article provides a method for consuming a Document Style Web Service using the UTL_DBWS package in the 11G version of the database.  UTL_DBWS is a PL/SQL database package that contains a series of commands that developers can use to create a runtime PL/SQL procedure or function that will allow for the transfer of information from a web service to the database.

SCOPE

This article is intended for Web Service Developers.

DETAILS

The steps to be used are as follows: 

1) Download the LATEST copy of the UTL_DBWS utility zip file from the Oracle Technology Network (OTN).  This file, for an 11G database, is named dbws-callout-utility-10131.zip and can be obtained from here. 

2) Extract the contents of the zip file to the $ORACLE_HOME directory.  This will place the contents of the zip in the $ORACLE_HOME/sqlj/lib directory.  

3) The 11.1 version of the database contains the UTL_DBWS PL/SQL package in the SYS schema by default, but the 11.2 version does not have this loaded automatically.  If you are using the 11.2 version, you can run the appropriate PL/SQL package body and specification in order to install the core PL/SQL code into whatever schema you wish to use.  The code used for the example will assume that the SYS schema was used, as per the default installation for the 11.1 version, but it is possible to load this package into the same schema that is being used for the loadjava commands performed in step 4 below.  The packages to be loaded are named utl_dbws_body.sql and utl_dbws_decl.sql and exist in the $ORACLE_HOME/sqlj/lib directory after the callout utility zip has been unzipped into the $ORACLE_HOME directory.  Once the package is in place, is important to perform a couple of checks to ensure the database environment is ready for use with the callout mechanism. 

a) Make sure the initialization parameters SHARED_POOL_SIZE and JAVA_POOL_SIZE are equal to or greater than 96M and 80M, i.e.,

shared_pool_size=96M 
java_pool_size=80M

b) Check to ensure that the jvm objects in the SYS schema are valid.  You can check this by logging into the database as SYS and running the following query:

SELECT owner, status, count(*) FROM DBA_OBJECTS 
WHERE OBJECT_TYPE='JAVA CLASS' 
GROUP BY owner, status;

If there are classes that are listed as being in an 'INVALID' state, you can run the following script to attempt to make these objects VALID: 

$ORACLE_HOME/rdbms/admin/utlrp.sql 

Once this has been run, recheck the status of your Java objects.  If there are still any that are INVALID, it may be necessary to contact Oracle Support to determine how to make these objects VALID before continuing. 

4) Load the necessary core web services callout jar files into the database.  This step is to load the core Java components and is a completely separate action from loading the PL/SQL package as described in the previous steps.  This means that the considerations for completing this step are entirely different from the loading of the PL/SQL components.  In the 11gR2 version of the database,  it has been determined that loading the jars into ths SYS schema will cause conflicts with existing classes already loaded in this schema by default so a user created schema will need to be used for  loading of these jars (CONNECT, RESOURCE and CREATE PUBLIC SYNONYM are the minimum grants that have to be performed on this schema).  For 11.1.0.x, this Java loading restrication does not exist, and it is possible to load the jars into the SYS scheama, although it is strongly recommended that a user defined schema be created for the loading of the jars in this version as well.  By separating the loading of the callout classes into its own schema, even for the 11gR1 version, it should ensure that no conflicts will occur with classes that have been already loaded into the database in other schemas, so it is good practice in all cases to create a user defined schema for the loading of the jar files necessary for the use of the UTL_DBWS package.

When loading the jar files in the desired schema, make sure the PATH environment variable includes the $ORACLE_HOME/bin directory.  From a terminal window, run the following commands:

cd $ORACLE_HOME/sqlj/lib (replacing $ORACLE_HOME with the proper directory structure) 
loadjava -u username/password -r -v -f -s -grant public -genmissing dbwsclientws.jar dbwsclientdb11.jar

Replace the username/password designation with whatever applies in your particular database environment. 

5) There are a series of permission grants that must be performed. These grants only have to be performed once before the functionality is available. From the SYS schema, run the following commands:

execute dbms_java.grant_permission('<SCHEMA>','SYS:java.util.PropertyPermission','http.proxySet','write'); 
execute dbms_java.grant_permission('<SCHEMA>','SYS:java.util.PropertyPermission','http.proxyHost', 'write'); 
execute dbms_java.grant_permission('<SCHEMA>','SYS:java.util.PropertyPermission','http.proxyPort', 'write'); 
execute dbms_java.grant_permission('<SCHEMA>','SYS:java.lang.RuntimePermission', 'accessClassInPackage.sun.util.calendar',''); 
execute dbms_java.grant_permission('<SCHEMA>','SYS:java.lang.RuntimePermission','getClassLoader',''); 
execute dbms_java.grant_permission('<SCHEMA>','SYS:java.net.SocketPermission','*','connect,resolve'); 
execute dbms_java.grant_permission('<SCHEMA>','SYS:java.util.PropertyPermission','*','read,write'); 
execute dbms_java.grant_permission('<SCHEMA>','SYS:java.lang.RuntimePermission','setFactory','');

The <SCHEMA> designation is to be replaced with the actual schema name being used. The name must also be designated in caps. 

If your environment does not use a proxy server, the first three dbms_java.grant_permission statements listed do not need to be executed and can be ignored. 

6) As a test, the following UTL_DBWS function can be used as a test to ensure the callout mechanism is installed correctly. The function calls an external web service that converts Celsius temperatures to Fahrenheit.

CREATE OR REPLACE FUNCTION celciusToFahrenheit(temperature NUMBER) RETURN VARCHAR2 AS 

service_ sys.utl_dbws.SERVICE; 
call_ sys.utl_dbws.CALL; 
service_qname sys.utl_dbws.QNAME; 
port_qname sys.utl_dbws.QNAME; 
response sys.XMLTYPE; 
request sys.XMLTYPE; 

BEGIN 
sys.utl_dbws.set_http_proxy('myproxyserver:8080'); 
service_qname := sys.utl_dbws.to_qname(null, 'CelciusToFahrenheit'); 
service_      := sys.utl_dbws.create_service(service_qname); 
call_         := sys.utl_dbws.create_call(service_); 
sys.utl_dbws.set_target_endpoint_address(call_, 'http://webservices.daehosting.com/services/TemperatureConversions.wso'); 
sys.utl_dbws.set_property( call_, 'OPERATION_STYLE', 'document'); 
request       := sys.XMLTYPE('<CelciusToFahrenheit xmlns="http://webservices.daehosting.com/temperature"><nCelcius>'||temperature||'</nCelcius></CelciusToFahrenheit>'); 
response      :=sys.utl_dbws.invoke(call_, request); 
return response.extract('//CelciusToFahrenheitResult/child::text()', 'xmlns="http://webservices.daehosting.com/temperature"').getstringval(); 
END; 
/

NOTE: The SYS prefix for the UTL_DBWS calls assumes that the PL/SQL package is loaded into SYS.  If this is not the case in the particular environment being used, and the package is loaded into another schema, please make the adjustments necessary to the code to reflect the schema that holds the UTL_DBWS package.

BACKGROUND OF CODE USED 
------------------------ 

The sys.utl_dbws.set_http_proxy call is used take into account any proxy server that would exist in the database environment. The value provided is an example of the syntax, and must be replaced with the values that suit the database environment. This line of code can be removed entirely if no proxy server exists in the environment. 

The sys.utl_dbws.to_qname call provides a mechanism to provide the service and call name necessary for the operations to be performed. Due to the simplicity of the web service being used for testing, null is all that is necessary to provide for the service name. In a production environment, this would likely be a particular value that would have to be determined and provided in place of null. In this case, the operation name is CelciusToFarenheit. This value can be found by examining the WSDL, and looking for the <operation> tag and determining the name parameter. For the example above, the WSDL can be found at the following URL: 

http://webservices.daehosting.com/services/TemperatureConversions.wso?WSDL 

The request parameter is created as an XMLTYPE, as Document Style web services use xml parameters both for input and output. It is necessary to determine what the web service is expecting to receive in it's entirety as a request in order to supply the correct information to this parameter. Determine the syntax contained in the <soap:Body> tag for the request envelope of the service to get the value to be passed in the XMLTYPE variable. For the same reason, the response is an XMLTYPE as well. This makes it simple to use the extract method of this type to get the result in a form that can be used for whatever purposes desired.. 

The output below shows the function in action.

SQL> SELECT celciusToFahrenheit(30) from dual; 


CELCIUSTOFAHRENHEIT(30) 
------------------------------------------------------------------------------ 
86 

SQL>

This example was built using a third-party web service. If you find in testing that this fails to function, it may be due to the web service being taken offline. By executing the following URL in a browser window: 

http://webservices.daehosting.com/services/TemperatureConversions.wso 

You should be able to determine if this is the case. 

If you would prefer not to use UTL_DBWS for your web services callout, there is another approach can be taken.  This uses the JPublisher utility to create a Java Stored Procedure with a PL/SQL wrapper that can be used to access the code.  This approach is outline in the following note, available on MetaLink: 

Note 469588.1 - DBWS Callout Utilities User's Guide for RDBMS 11.1 

For more information on making web service callouts from the database, see: 

Callout Users Guide 
UTL_DBWS Package Reference
Developing a Web Service Client in the Database 

 

---

Join the Java Development MOS Community forum for general discussions, questions, best practices, and other valuable information on: Oracle JDeveloper and ADF, Oracle WebLogic - JEE Programming (EJB, JMS etc), Oracle JDBC, Oracle Web Services (incl. DBWS Callout Utility), Oracle Web Services Manager (OWSM), Oracle Service Registry (OSR), Oracle Toplink (EclipseLink), Sun NetBeans IDE / Java Studio Creator & Java Studio Enterprise, OC4J, KODO.