In this Document





Oracle Database - Enterprise Edition - Version and later

Web Services - Version and later

Information in this document applies to any platform.


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.


This article is intended for Web Service Developers.


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 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.,



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 


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: 


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>','','*','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.


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; 



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_, ''); 

sys.utl_dbws.set_property( call_, 'OPERATION_STYLE', 'document'); 

request       := sys.XMLTYPE('<CelciusToFahrenheit xmlns=""><nCelcius>'||temperature||'</nCelcius></CelciusToFahrenheit>'); 

response      :=sys.utl_dbws.invoke(call_, request); 

return response.extract('//CelciusToFahrenheitResult/child::text()', 'xmlns=""').getstringval(); 



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.



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: 

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; 





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:

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.


  1. CSS3颜色渐变模式

       1.线性渐变:linear-gradient 语法:<linear-gradient> = linear-gradient([ [ <angle> | to <si ...

  2. OC 初识NSString,self关键字,继承,成员变量的可见性,description方法

    OC 初识NSString,self关键字,继承,成员变量的可见性,description方法 初识 NSString: char * string = "旭宝爱吃鱼"; 常量字符 ...

  3. nios II--实验3——led 100M软件部分

    软件开发 参照实验二(led),该实验与实验二(led)的不同之处在于系统的时钟由50M提成为100M.运行结果,在调试窗口输出Hello from Nios II!,并且板上的四个LED灯流动显示, ...

  4. Android js相互调用

    一.webview相当于android中的浏览器,基于webkit开发,可以浏览网页文件,支持css javas cript 以及html webview.getSettings().setJavaS ...

  5. iOS开发中代理使用出现的问题解决

    在给自定义的LHQTabBar设置代理的时候,定义的代理的属性的时候此时会报一个警告 我们需要遵守UITabBarDelegate的协议才行, 不过此时还有警告,警告已经变成了 此时我们需要在.m文件 ...

  6. Cocos2dx游戏源码合集(BY懒骨头+持续更新+2014.02.21)

    转自: 声明: <萝莉快跑><喵汪大战>两个demo的原作者b ...

  7. Android Activity间传值

    Android中不同的Activity之间的传值方式(Main为当前Activity,Login为目标Activity) 1.使用Intent Intent intent = new Intent(M ...

  8. lpc1768的rit使用

    LPC1768在系统滴答定时器和通用定时器之外还引入了一个定时器,叫做重复定时器RIT,该定时器只能用于定时操作,带有一个中断,我个人的感觉,这似乎是为了延时函数设计的一个定时器 那么使用该定时器时遵 ...

  9. 学习Java 以及对几大基本排序算法(对算法笔记书的研究)的一些学习总结(Java对算法的实现持续更新中)

    Java排序一,冒泡排序! 刚刚开始学习Java,但是比较有兴趣研究算法.最近看了一本算法笔记,刚开始只是打算随便看看,但是发现这本书非常不错,尤其是对排序算法,以及哈希函数的一些解释,让我非常的感兴 ...

  10. Harbor 使用 Helm 一键安装

    安装 Harbor Harbor 支持多种安装方式,源码目录下面默认有一个安装脚本(make/,采用 docker-compose 的形式运行 Harbor 各个组件,和前面的课 ...