Installing and Configuring Spatial Web Service in OC4J

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

Approximately 1 hour

This tutorial covers the following topics:

bullet
bullet
bullet
bullet
bullet
bullet
bullet
bullet
bullet

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.

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

bullet

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.

bullet

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.

bullet

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

Before you perform this tutorial, you should:

bullet

Install Oracle Database 11g software and create a database.

bullet

Install the Oracle Database 11g companion CD.

bullet

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

bullet

Download the latest J2SE from Javasoft and install.

bullet

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

bullet Download the xsds.jar file into your working directory.
bullet

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

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:

bullet
bullet
bullet
bullet
bullet
bullet

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

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

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

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,

bullet
bullet
bullet
bullet
bullet

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.

Change 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

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

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

1.

Set the following variables in the compileAndRunClient.sh file:

bullet
bullet
bullet
bullet
bullet

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

In this tutorial, you learned how to:

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

Back to Topic List

Move your mouse over this icon to hide all screenshots.