Installing and Configuring Spatial Web Service in OC4J

Purpose

This tutorial describes how to publish a web service that uses spatial data.

Time to Complete

Approximately 1 hour

Topics

This tutorial covers the following topics:

 Overview
 Prerequisites
 Configuring OC4J
 Starting OC4J
 Deploying Your EAR File
 Configuring Your Data Sources
 Verifying Your Data Sources
 Configuring and Running the Client
 Summary

Viewing Screenshots

 Place the cursor over this icon to load and view all the screenshots for this tutorial. (Caution: This action loads all screenshots simultaneously, so response time may be slow depending on your Internet connection.)

Note: Alternatively, you can place the cursor over an individual icon in the following steps to load and view only the screenshot associated with that step. You can hide an individual screenshot by clicking it.

Overview

This tutorial introduces the Oracle Spatial support for spatial Web services. Oracle Spatial provides the following types of Web services:

Web Feature Services (WFS) enables users to find/update features (e.g. roads, rivers, and so on) based on their relationship to a location, and other non-spatial attributes. This web service is Oracle Spatial implementation of the Open GIS Consortium (OGC) specification of WFS 1.0.0.

Catalogue services for Web (CSW) supports the ability to publish and search collections of descriptive information (metadata) for data, services, and related information objects. This web service is Oracle Spatial implementation of the OGC specification of CSW 2.0.0.

Open Location Services (OpenLS) provides location-based services like geocoding, mapping, routing, and yellow pages. Geocoding enables users to associate spatial locations (longitude and latitude coordinates) with postal addresses.

Mapping enables users to generate maps based on spatial location information. Yellow Pages enables users to find businesses by name or category based on their relationship to a location. Routing provides driving information and instructions for individual or multiple routes.

This web service provides access to the different existing capabilities in Oracle Spatial, e.g. routing, geocoding, mapping, directory functionality conforming to OpenLS 1.1 specification defined by OGC.

In this tutorial, you learn how to install and configure Spatial web service in OC4J (Oracle Containers for Java).

You will learn how to run web service client demos for the different web services discussed above (WFS, CSW and OpenLS) in the tutorial titled, " Running the Oracle Spatial Web Services" .

Back to Topic List

Prerequisites

Before you perform this tutorial, you should:

Install Oracle Database 11g software and create a database.

Install the Oracle Database 11g companion CD.

Download Oracle JDeveloper from OTN and unzip it into any directory.

Download the latest J2SE from Javasoft and install.

Create a working directory and copy the wsclient.jar from the $ORACLE_HOME/md/demo/ws/client directory into your working directory.

 Download the xsds.jar file into your working directory.

Make sure the following users are unlocked: mdsys, spatial_csw_admin_usr and spatial_wfs_admin_usr Open SQL*Plus and execute the following commands:

                                 
connect sys/oracle as sysdba
alter user mdsys identified by oracle account unlock;
alter user spatial_csw_admin_usr identified by oracle account unlock;
                                 
alter user spatial_wfs_admin_usr identified by oracle account unlock;
                              

Back to Topic List

Configuring OC4J

This section describes the steps needed to configure the oc4j to install Spatial Web service and the Spatial Web service demo users. Perform the following steps:

 Configuring example users
 Configuring the OC4J path settings
 Creating and registering shared libraries
 Copy files into shared library directory
 Patching xmlparserv2.xdk file
 Extracting the wsclient.jar file

Back to Topic List

Configuring example users

1.

From your terminal window, enter the following commands:

                               
cd <jdevhome directory>/j2ee/home/config
gedit system-jazn-data.xml
                            

where <jdevhome directory> is the directory location where JDeveloper was unzipped.

 

2.

Open the exampleusers.txt file from here. Select all the text and then press Ctrl + C to copy. Switch to the gedit window on your Linux desktop. Press Ctrl + V to add the following statements after the last <user> section in the system-jazn-data.xml file.

                               
                 
                                
<user>
                                  
<name>SpatialWsUser0</name>
<display-name>Spatial WS user 0</display-name>
<description>Used for SpatialWs</description>
<credentials>!welcome</credentials>
</user>
<user>
<name>SpatialWsUser1</name>
<display-name>Spatial WS user 1</display-name>
<description>Used for SpatialWs</description>
<credentials>!welcome</credentials>
</user>
<user>
<name>SpatialWsUser2</name>
<display-name>Spatial WS user 2</display-name>
<description>Used for SpatialWs</description>
<credentials>!welcome</credentials>
</user>
<user>
<name>SpatialWsUser3</name>
<display-name>Spatial WS user 3</display-name>
<description>Used for SpatialWs</description>
<credentials>!welcome</credentials>
</user>
<user>
<name>wfs_rel_user</name>
<display-name>wfs_rel_user</display-name>
<description>Spatial WFS user </description>
<credentials>!wfs_rel_user</credentials>
</user>

<user>
<name>wfs_doc_user</name>
<display-name>wfs_doc_user</display-name>
<description>Spatial WFS user </description>
<credentials>!wfs_doc_user</credentials>
</user>
<user>
<name>csw_user</name>
<display-name>csw_user</display-name>
<description>Spatial CSW user </description>
<credentials>!csw_user</credentials>
</user>

In the gedit window, from the File menu, select Save to save the change or click the Save icon on the toolbar. From the File menu, select Quit to exit the editor.

Back to Topic

Configuring the OC4J path settings

1.

From your terminal window, enter the following commands:

                               
cd <jdevhome directory>/bin
gedit oc4j
                            

where <jdevhome directory> is the directory location where JDeveloper was unzipped.

Note: If the file opens in a read-only mode, exit the editor. In the terminal window, log-in as root and use the chmod command to change the access to read-write and executable. Then re-open the file in gedit. The command to change the access mode is as follows:

                               
                                 
chmod 777 oc4j
                              
                            
2.

Add the following statements in the beginning of the file.

                               
                                 
ORACLE_HOME=<jdevhome directory>
                                  
JAVA_HOME=<jdk home directory>

Save the file and exit the editor.(could not save the file as oracle user;when logged in as su, was able to save the file)

 

Back to Topic

Creating and registering shared libraries

1.

From your terminal window, enter the following commands to create the shared library directories:

                               
mkdir <jdevhome directory>/j2ee/home/shared-lib/sdows
                                
mkdir <jdevhome directory>/j2ee/home/shared-lib/sdows/1.0

where <jdevhome directory> is the directory location where JDeveloper was unzipped.

 

2.

To register the library in the server.xml file, enter the following commands:

                               
                                 
                                   
cd <jdevhome directory>/j2ee/home/config
gedit server.xml

                                      
                                                                                                
                            

Then add the following statements right before the rmi-config statement.

                               
<shared-library name="sdows" version="1.0">
                                
<code-source path="*"/>
<import-shared-library name="oracle.xml"/>
<import-shared-library name="oracle.jdbc"/>
</shared-library>

Save the file and exit the editor.

 

3.

Ensure that the present working directory is <jdevhome directory>/j2ee/home/config. To register the library in the application.xml file, enter the following commands:

                               
                                 
                                   
                                     
gedit application.xml

                                        
                                                                                                                                    
                            

Then add the following statements right before the </imported-shared-libraries> statement.

                               
<import-shared-library name="sdows"/>
                            

Save the file and exit the editor.

 

Back to Topic

Copy files into shared library directory

1.

From your terminal window, enter the following commands to copy the files from $ORACLE_HOME/md/jlib and $ORACLE_HOME/rdbms/jlib into the shared library directories you just created.

                               
cd <jdevhome directory>/j2ee/home/shared-lib/sdows/1.0
                               
cp $ORACLE_HOME/md/jlib/sdowfscs.jar .
                                
cp $ORACLE_HOME/md/jlib/sdoutl.jar .
cp $ORACLE_HOME/md/jlib/sdotype.jar . cp $ORACLE_HOME/md/jlib/sdoapi.jar .
cp $ORACLE_HOME/md/jlib/sdowshandlers.jar .
cp $ORACLE_HOME/md/jlib/sdowspool.jar .
cp $ORACLE_HOME/md/jlib/sdowshandlerols.jar . cp $ORACLE_HOME/rdbms/jlib/xdb.jar .

where <jdevhome directory> is the directory location where JDeveloper was unzipped and $ORACLE_HOME is your Oracle Database Home directory.

Back to Topic

Patching xmlparserv2.xdk file

1.

From your terminal window, enter the following commands to copy the xmlparserv2.jar file from $ORACLE_HOME/lib into the <jdevhome directory>/lib directory.

                               
cd <jdevhome directory>/lib
                              
cp $ORACLE_HOME/lib/xmlparserv2.jar .

, where <jdevhome directory> is the directory location where JDeveloper was unzipped and $ORACLE_HOME is your Oracle Database Home directory.

Back to Topic

Extracting the wsclient.jar file

1.

From your terminal window, enter the following commands to extract the wsclient .jar file supplied by this tutorial.

From your terminal window, enter the following commands:

                               
                                 
cd $CLIENT_HOME
                                                            
                                 
                                   
                                     
jar -xvf wsclient.jar
                                  
                                
                              
                            

where $CLIENT_HOME is the directory location where you want to extract the wsclient.jar file. You can extract the wsclient.jar file in anyone of your directory.

                               

                            

Back to Topic

Starting OC4J

This section describes how to start the oc4j instance. Perform the following steps:

1.

From your terminal window, enter the following commands:

                               
                                 
cd <jdevhome directory>/bin
                                
./oc4j -start

where <jdevhome directory> is the directory location where JDeveloper was unzipped

Note: You are asked to specify an admin password, enter admin . Enter admin again to confrm the password. You should see the message, "Oracle Containers for J2EE 10g (10.1.3.1.1) initialized", indicating that the OC4J server is started.

 

Back to Topic List

Deploying Your EAR File

This section describes how to deploy Spatial Web service in the oc4j instance started in the previous step. Perform the following steps:

1.

Open another terminal window and enter the following commands to set $JAVA_HOME variables. Ensure that the ORACLE_HOME variable is set. If not, set ORACLE_HOME variable to your Oracle Database home directory using the export command.

                               
                                 
export JAVA_HOME=/usr/java/<jdk dir>/
                              
                            

 

2.

Now you can deploy your EAR file. From your terminal window, enter the following command:

                               
                                 
                                   
$JAVA_HOME/bin/java -jar <jdev_home>/j2ee/home/admin.jar ormi://localhost oc4jadmin admin
 -deploy -file $ORACLE_HOME/md/jlib/sdows.ear -deploymentName sdows -bindWebApp 
default-web-site
                                
                              
                            

where $ORACLE_HOME is your Oracle Database home directory.

 

Back to Topic List

Configuring Your Data Sources

This section describes how to configure the data sources that will be used by our Spatial Web service. Perform the following steps:

1.

Before you can configure your data sources, you should stop the oc4j. From your terminal window, enter the following commands:

                               
                                 
cd <jdevhome directory>\bin
                              
                            
                               
                                 
                                   
./oc4j -shutdown -port 23791 -password admin
                                
                              
                            

Note: The port number can be found in the <jdevhome directory>/j2ee/home/config/rmi.xml file.

 

2.

From your terminal window, enter the following command:

                               
                                 
                                   
                                     
cd <jdevhome directory>/j2ee/home/applications/sdows/META-INF
gedit data-sources.xml
                                  
                                
                              
                            

where <jdevhome directory> is the directory location where JDeveloper was unzipped.

Configure each of the native data sources url, user and passwords parameters.

For the following native-data-sources,

 jdev-connection-WfsProxyConnection
 jdev-connection-NdmProxyConnection
 jdev-connection-CatalogProxyConnection
 jdev-connection-OpenLsProxyConnection
 jdev-connection-ConferenceProxyConnection

Change each occurrence of url, user, and password parameters to following:

                               
                                 
                                   
url="jdbc:oracle:thin:@localhost:1521:orcl"
                                                                                            
                                 
                                   
user="mdsys"
password="oracle"
                                
                              
                            

For native-data-sources, jdev-connection-CSW_ADMIN_CONN_NAME and jev-connection-WFS_ADMIN_CONN_NAME, change only the url and the password parameters to the following:

                               
                                 
                                   
url="jdbc:oracle:thin:@localhost:1521:orcl"
                                                                                            
                                 
                                   
password="oracle"
                                
                              
                            

When done, save the file and close.

 

3.

Load OGC WFS XSDs in any URL location. Extract the xsds.jar file into the <jdevhome directory/j2ee/home/default-web-app/examples/servlets/ directory. Note, this location is the location where the extracted files from the xsds.jar file will be stored.

To change to the directory location where you extract the xsds.jar file, enter the following commands:

                               
                                 
cd <jdevhome directory/j2ee/home/default-web-app/examples/servlets/
                              
                            

You must have downloaded the xsds.jar file (from the link in the Prerequisites section) in one of your directory locations. To extract the files from the xsds.jar file, enter the following command:

                               
                                 
jar -xvf <directorylocation where you downloaded the xsds.jar file>/xsds.jar
                              
                            

4.

Edit the WSConfig.xml file to specify the xsd files location url. From your terminal window, enter the following commands:

                               
                                 
                                   
cd <jdevhome directory>/j2ee/home/applications/sdows/sdows/WEB-INF/conf
gedit WSConfig.xml
                                
                              
                            

where <jdevhome directory> is the directory location where JDeveloper was unzipped.

In the WSConfig.xml file,change the wfs-xsd-loc-url to the path where the XSDS are saved, as mentioned below:

<wfs_xsd_loc_url>http://<machine_name>:8888/examples/servlets/xsds/</wfs_xsd_loc_url>

Remember to remove the comments tag.

Save the file and exit the editor.

 

5.

Edit wfsrelmd.sql, wfsdocmd.sql, and cswmd.sql to change the $DATA_DIR_PATH to the directory where src directory is. The src directory was created when you extracted the wsclient.jar file.

From your terminal window, enter the following commands:

                               
                                 
                                   
cd $CLIENT_HOME/src/sql
gedit wfsrelmd.sql
                                
                              

where $CLIENT_HOME is the directory location where you extracted the wsclient.jar file.

Replace the $DATA_DIR_PATH with the path of the src directory, as shown in the screenshot below.

                               
                                  
                              

Save the change.
                            

Similarly, edit the wfsdocmd.sql(in the same folder) and change the $DATA_DIR_PATH to the path of the src directory, as shown in the screenshot below. Save the file.


Edit cswmd.sql as shown in the screenshot: (You will find the $DATA_DIR_PATH variable almost towards the end of the file, therefore scroll down)


Save the files and exit the editor.

 

6.

Change the connection string (database machine name, port number, Oracle SID, and so on) to reflect your actual information in the following:

- For WFS: oracle.spatial.ws.admindemo.WFSAdminDemo.java file
- For CSW: oracle.spatial.ws.admindemo.CSWAdminDemo.java file

From your terminal window, enter the following commands:

                               
                                 
                                   
cd $CLIENT_HOME/src/oracle/spatial/ws/admindemo
gedit WFSAdminDemo.java

where $CLIENT_HOME is the directory location where you extracted the wsclient.jar file.
                                  
Edit the following statement as follows:
OracleConnection conn =
(OracleConnection) DriverManager.getConnection ("jdbc:oracle:thin:@localhost:1521:orcl","WFS_ADMIN_USR","WFS_ADMIN_USR");
Save the file.
Similarly, edit the CSWAdminDemo.java file.
                              

OracleConnection conn=
                                
(OracleConnection) DriverManager.getConnection ("jdbc:oracle:thin:@localhost:1521:orcl","csw_admin_usr","csw_admin_usr");

Save the file and exit the editor.

7.

In the TestWfsCsBase.java file, change myPort.setEndpoint("http://localhost:8888/SpatialWS-SpatialWS-context-root/SpatialWSSoapHttpPort"); to reflect your OC4J server machine name and port number . For this tutorial, you can enter the machine name as localhost and port number as 8888.

From your terminal window, enter the following commands:

                               
                                 
                                   
cd $CLIENT_HOME/src/oracle/spatial/ws/svrproxy
gedit TestWfsCsBase.java
                                
                              
                            

where $CLIENT_HOME is the directory location where you extracted the wsclient.jar file.

Ch
                              
ange to
                            
                               
                                 
myPort.setEndpoint
 
                                
                              
                                 
("http://localhost:8888/SpatialWS-SpatialWS-context-root/SpatialWSSoapHttpPort");
                              
                            
                               
                                 
                                   
                                     
                                       
                                          

                                                                                                                                                                          
                            
8.

You now need to restart the oc4j. From your terminal window, enter the following commands:

                               
                                 
cd <jdevhome directory>/bin
                                
./oc4j -start

where <jdevhome directory> is the directory location where JDeveloper was unzipped

 

Back to Topic List

Verifying Your Data Sources

The following steps help you to verify the datasource parameters needed for the demos have been configured properly. Perform the following steps:

1.

Open a browser window, and enter the following URL:

                               
http://<hostname>:8888/em 

                            

For the tutorial environment you can use localhost for the hostname. Login as oc4jadmin with the password, admin. This is the password you created when you started the oc4j. Then click Login.

 

2.

In the Supply Administration Credentials page, enter the credentials for a user in the oc4j-administrators group. These credentials are needed by Application Server Control to maintain proxy connections. Enter admin as the password.

 

3.

Click Administration tab.

 

4.

Click the Go to Task icon for the Services: JDBC Resources task.

 

5.

Your data sources are listed. Click the Test Connection icon for one of the data sources.

You get a Test Connection page, click Test.

You get a successful connection confirmation.

Click Logout.

 

Back to Topic List

Configuring and Running the Client

Now you can compile and run the client. Perform the following steps:

1.

Set the following variables in the compileAndRunClient.sh file:

 JAVA_HOME Set to the jdk location
 spatialws_lib Set to the JDeveloper installation directory
 spatialws_server_lib Set to the sdows shared library in OC4J server
 spatial_ws_srcpath Set to the src directory location extracted from the wsclient.jar file
 spatialws_target Set to the target path for class files to be generated. Re-use the source path

Enter the following commands:

                               
                                 
cd $CLIENT_HOME/src
                                                            
                                 
gedit compileAndRunClient.sh
                              
                            

where $CLIENT_HOME is the directory location where you extracted the wsclient.jar file.

The screenshot shows the configured parameters.

Save the file and exit the editor.

 

2.

In your terminal window, enter the following commands:

                               
                                 
./compileAndRunClient.sh
                              
                            

 

Back to Topic List

Summary

In this tutorial, you learned how to:

 Configure and start OC4J
 Deploy your EAR file
 Configure and verfiy your data source
 Configure and run the client

Back to Topic List

 Move your mouse over this icon to hide all screenshots.

 

Left Curve
Popular Downloads
Right Curve
Untitled Document