Note:
The purpose of this article is to provide a step-by-step
instruction on how to install the DBWS Callout Utilities on Oracle Database
Server 11g and how to verify that it works properly.
After completing this installation procedure, there will
be an environment for an OC4J Standalone instance hosting a very simple document
style web service and an environment for the Oracle Client. The article assumes
that there is an environment for Oracle Database Server 11g already. All of
this environments may be placed on different machines. Anyway, it has been
found convenient to have this environments on one machine for an initial installation
and test of the DBWS Callout Utilities. This does rule out network problems
from affecting the proper operation of the DBWS Callout Utilities.
-
Setup the appropriate environment for the Oracle Client
export ORACLE_BASE=/app/oracle
export ORACLE_HOME=/app/oracle/product/client.11.1.0.6.0
export PATH=.:$ORIG_PATH:$ORACLE_HOME/bin:$ORACLE_HOME/jdk/bin
export LD_LIBRARY_PATH=$ORIG_LD_LIBRARY_PATH:$ORACLE_HOME/lib
export TWO_TASK=db1110
On Unix/Linux the environment variable TWO_TASK can be
used to defines the default TNS alias for the database service to connect
to. The equivalent name for the environment variable on Windows is "LOCAL".
Alternatively the TNS alias can be qualified explicitly
when connecting. Further details can be found in the documentation on SQL*Plus,
JPublisher and loadjava (Java Developer's Guide 11g).
-
Install Oracle Client 11.1.0.x with Installation Type
"Administrator"
This will install all the tools and jars required to work
with the DBWS Callout Utilities.
-
Configure a Oracle Net Alias According To the Environment
Variable "TWO_TASK" respectively "LOCAL".
-
Drop The Package "UTL_DBWS" in Schema "SYS"
Later on this package will be installed into the schema
dedicated for the classes of the DBWS Callout Utilities. It is only required
in "SYS" if the DBWS Callout Utilities classes have been installed into
"SYS".
drop package UTL_DBWS;
-
Check the OracleJVM for Invalid Classes
The schema "SYS" and the schema into which the DBWS Callout
Utilities should be installed must not have invalid classes. The status
of all the java classes installed on the Oracle Database Server instance
can be checked as SYSDBA with following SQL statement:
SELECT owner, status, count(*) FROM DBA_OBJECTS
WHERE OBJECT_TYPE='JAVA CLASS'
GROUP BY owner, status;
For a standard installation of Oracle Database Server
11.1 this SQL statement should return about 20000 valid classes for the
owner/schema "SYS".
It is very difficult to resolve invalid classes once they
are in schema "SYS". There is a huge number of classes in this schema and
it is not easy to find out the dependencies. It is a lot easier to resolve
invalid classes in schemas, that are not system schemas of the Oracle Database
Server, because in this case all uploaded jar files and classes with their
dependencies should be known to the user.
The complete reinitialization of the OracleJVM is usually
the most efficient approach to resolve problems with invalid classes in
schema "SYS", even though this is a risky and time consuming procedure.
The following document gives clear advises:
Note
457279.1 How to Reload the JVM in 11.1.0.x
Note:
Many users of the DBWS Callout Utilities have run into
problems with invalid classes in schema "SYS" because they had followed
the advises for Oracle SOAP and in addition the advises for Oracle JAX-RPC
in the original "DBWS Callout Utilities 10.1.3.1 User's Guide", that ships
with the product's download archive. The java archives required by Oracle
SOAP and Oracle JAX-RPC do not match with each other. If the java archives
have been installed into the schema "SYS", then the reinitialization of
the OracleJVM is the most efficient approach to resolve the resulting
problems.
-
Configure the OracleJVM
Preparing the database consists mainly in loading the
Web Services client stack into the database. Loading the client stack requires
extra Java space inside the OracleJVM to resolve and store load jar files.
Make sure the initialization parameters SHARED_POOL_SIZE and JAVA_POOL_SIZE
are equal to or greater than 132M and 80M, i.e.,
shared_pool_size=132M
java_pool_size=80M
Depending on the number of Java classes already loaded
into the database, the two parameters may need to be increased beyond 132M
and 80M.
In SQL*Plus you can check the size of this initialization
parameters as SYSDBA:
show parameter SHARED_POOL_SIZE
show parameter JAVA_POOL_SIZE
Oracle Database Server 10g is typically configured to
use "Automatic Shared Memory Managerment". In this case the initialization
parameters can be configured dynamically during runtime and no database
restart is required.
alter system set SHARED_POOL_SIZE=132M scope=both;
alter system set JAVA_POOL_SIZE=80M scope=both;
-
Download the Oracle DBWS Callout Utility 10.1.3.1
-
Unzip the Content of the ZIP File to $ORACLE_HOME (Oracle
Database Server Environment)
e.g.:
% unzip dbws-callout-utility-10131.zip sqlj/* -d $ORACLE_HOME
% unzip dbws-callout-utility-10131.zip samples/* -d $ORACLE_HOME/sqlj
% unzip dbws-callout-utility-10131.zip README* -d $ORACLE_HOME/sqlj
-
Modify the CLASSPATH in $ORACLE_HOME/sqlj/bin/jpub
TMPCLASSPATH=$ORACLE_HOME/sqlj/lib/dbwsa.jar:$ORACLE_HOME/jdk/lib/dt.jar:\
$ORACLE_HOME/jdk/lib/tools.jar:\
$ORACLE_HOME/jlib/jssl-1_1.jar:$ORACLE_HOME/jdbc/lib/ojdbc5.jar:\
$ORACLE_HOME/sqlj/lib/runtime12.jar:$ORACLE_HOME/jlib/orai18n.jar:\
$ORACLE_HOME/sqlj/lib/translator.jar:$ORACLE_HOME/javavm/lib/aurora.zip:\
$ORACLE_HOME/rdbms/jlib/xdb.jar:$ORACLE_HOME/lib/xsu12.jar:\
$ORACLE_HOME/jlib/jndi.jar:$ORACLE_HOME/rdbms/jlib/aqapi.jar:\
$ORACLE_HOME/rdbms/jlib/jmscommon.jar:$ORACLE_HOME/lib/xmlparserv2.jar:\
$CLASSPATH
export TMPCLASSPATH
Note:
On Microsoft Windows operating systems a binary executable
will be used to start JPublisher (jpub.exe). Therefore the classpath in
the unix shell script will not be used. The environment variable CLASSPATH
must be setup instead.
set ORACLE_HOME=/app/oracle/product/client.11.1.0.6.0
set CLASSPATH=%ORACLE_HOME%\sqlj\lib\dbwsa.jar;%ORACLE_HOME%\jdk\lib\dt.jar;^
%ORACLE_HOME%\jdk\lib\tools.jar;^
%ORACLE_HOME%\jlib\jssl-1_1.jar;%ORACLE_HOME%\jdbc\lib\ojdbc5.jar;^
%ORACLE_HOME%\sqlj\lib\runtime12.jar;%ORACLE_HOME%\jlib\orai18n.jar;^
%ORACLE_HOME%\sqlj\lib\translator.jar;%ORACLE_HOME%\javavm\lib\aurora.zip;^
%ORACLE_HOME%\rdbms\jlib\xdb.jar;%ORACLE_HOME%\lib\xsu12.jar:^
%ORACLE_HOME%\jlib\jndi.jar;%ORACLE_HOME%\rdbms\jlib\aqapi.jar;^
%ORACLE_HOME%\rdbms\jlib\jmscommon.jar;%ORACLE_HOME%\lib\xmlparserv2.jar:^
;%CLASSPATH%
-
Make JPublisher and JDK 1.5.0 available for an Oracle
Client Operating System Shell
Oracle Client 11g ships with a JDK 1.5.0 already. The
JDK being used for JPublisher must match with the version of the OracleJVM
the generated classes will be deployed to.
e.g.:
% export PATH=$ORACLE_HOME/jdk/bin:$PATH
% echo $PATH
/app/oracle/product/client.11.1.0.6.0/jdk/bin:/app/oracle/product/client.11.1.0.6.0/bin:/usr/local/bin:/usr/bin:.
-
Load the WebService Client into Oracle Database Server
% loadjava -u scott/tiger -r -v -f -genmissing dbwsclientws.jar dbwsclientdb11.jar
Note:
The loadjava commands above load the Oracle JAX-RPC
client into the target schema. By default this classes will only be available
for the target user. Other users require execute privileges and synonyms
for this classes, if such users should also be able to have web service
callouts.
It is also possible to install this jar files into
the user SYS and at the same time JPublisher can create public synonyms
and grant the required privileges to PUBLIC.
e.g.:
% loadjava -u sys/change_on_install -r -v -f -genmissing -s -grant public
dbwsclientws.jar dbwsclientdb11.jar
The disadvantage of this approach is, that a number
of classes in SYS will be replaced by more recent versions packaged with
the loaded jar files. Whenever "dropjava" is used to remove this jar files
from the user SYS, many other classes depending on the previously overwritten
and now removed classes will be invalidated. It might be required to reinitialize
the OracleJVM.
-
With SQL*Plus Grant the Required Privileges to the Target
User as SYSDBA
SQL> call dbms_java.grant_permission( 'SCOTT', 'SYS:java.lang.RuntimePermission',
'shutdownHooks', '' );
SQL> call dbms_java.grant_permission( 'SCOTT', 'SYS:java.util.logging.LoggingPermission',
'control', '' );
An additional privilege is required, if the web service
client has not been installed into schema SYS, but into the target user
(e.g. SCOTT).
SQL> call dbms_java.grant_permission( 'SCOTT', 'SYS:java.lang.RuntimePermission',
'setFactory', '' );
-
Create and Deploy the Web Service Client Proxy
% jpub -u scott/tiger -sysuser sys/change_on_install \
-proxywsdl=http://localhost:8888/javacallout/javacallout?WSDL \
-endpoint=http://localhost:8888/javacallout/javacallout
Note:
The following resulting output shows some errors that
can be ignored without concerns.
tmp/src/genproxy/HttpSoap11ClientJPub.java
plsql_wrapper.sql
plsql_dropper.sql
plsql_grant.sql
plsql_revoke.sql
Executing plsql_dropper.sql
Executing plsql_wrapper.sql
Executing plsql_grant.sql
Loading plsql_proxy.jar
errors : source genproxy/runtime/HelloServiceEJB_SerializerRegistry
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.
errors : source genproxy/HttpSoap11ClientJPub
Note: genproxy/HttpSoap11ClientJPub uses or overrides a deprecated
API.
Note: Recompile with -Xlint:deprecation for details.
-
With SQL*Plus test the Sample Web Service as the Target
User "SCOTT"
SQL> select jpub_plsql_wrapper.sayhello('hello') from dual;
JPUB_PLSQL_WRAPPER.SAYHELLO('HELLO')
-----------------------------------
HELLO!! You just said :hello
-
Install The Package "UTL_DBWS" Into "SCOTT"
If the DBWS Callout Utilities jar files had been installed
into a dedicated schema, then the classes will not be available for the
package "UTL_DBWS" in schema "SYS".
SQL> @?/sqlj/lib/utl_dbws_decl.sql
SQL> @?/sqlj/lib/utl_dbws_body.sql
-
Create a Copy of Script "test-plsql-dii.sql"
cp $ORACLE_HOME/sqlj/samples/test-plsql-dii.sql $ORACLE_HOME/sqlj/samples/my-test-plsql-dii.sql
-
Remove the Schema Qualifiers From "my-test-plsql-dii.sql"
The script qualifies the package "UTL_DBWS" with the schema
"SYS". Now, that "UTL_DBWS" is located in the dedicated schema all the schema
qualifiers can be removed.
-
Modify the Web Service Endpoint in the Test Script "$ORACLE_HOME/sqlj/samples/test-plsql-dii.sql"
as Required By the Test Web Service
e.g.:
utl_dbws.set_target_endpoint_address(call_, 'http://localhost:8888/javacallout/javacallout');
-
With SQL*Plus run the script "test-plsql-dii.sql"
SQL> @?/sqlj/samples/my-test-plsql-dii.sql
PL/SQL DII client return HELLO!! You just said :hello
Bookmark
