BLOB Access
iPlanet^TM Application Server Samples

If you already went through the deployment process of BLOB you can run the application by clicking here.

This sample can only be used with a Third Party JDBC driver as the iPlanet native JDBC drivers do not support BLOBs.

Overview

The BLOB sample application provides a web-based interface to an object repository in a database.  Two servlets provide the client with the ability to manage the storage of files in the database, enabling them to insert, update, delete and fetch the files.  Note that currently the majority of JDBC drivers do support the use of the JDBC 2.0 BLOB datatype.  In the cases where the JDBC 2.0 BLOB interface is not available, the driver will typically map the databases underlying blob-like datatype to the JDBC Long Varbinary type, for example.  The servlets in this sample can use either interface.

The repository is a simple database table containing a BLOB column (or similar datatype) which holds the file data along with the filename, size and mime type of the stored content.

Setting Up the Environment

Getting Started includes a checklist of pre-requisites for deploying the sample applications to iPlanet.

Configuring the Database describes how to setup the database schema, and register the JDBC data sources for the BLOB application.

Select one of two approaches to deploying and registering the application:

Command Line-based Deployment describes how to manually register the blob application in iPlanet using a Command Line Interface (CLI). This is the fastest means of deploying the BLOB sample to the application server.

GUI-based Deployment describes how to use the iPlanet Deployment Tool to import and deploy the BLOB application. Alternatively, you can also assemble the application from scratch and deploy it using the Deployment Tool.

Running the Application describes how to start the application, navigate through it and how to troubleshoot in the event of problems.

Compiling and Assembling the Application describes how to use command line tools to recompile the sources and rebuild the WAR module and the overall EAR file.

Configuring the Database

Ensure Database Requirements are Met

Ensure Database Driver is Registered

Identify or Create a Database User

Create the Sample Database Tables

Ensure Database Requirements are Met

Note: This sample is not supported with Pointbase as the dtaabase since there is no BLOB support with Pointbase.

See the iPlanet Application Server Release Notes for database version requirements. Database setup scripts are provided for the following databases:

• Oracle
      bin_ora.sql, blob_ora.sql
• Informix
      bin_ifmx.sql, blob_ifmx.sql
• MS SQL Server
      bin_mssql.sql
• Sybase
      bin_syb.sql
• IBM DB/2
      bin_db2.sql

Currently this sample has been test successfully against the following databases and third party drivers:

• Oracle 8.1.6 with Oracle JDBC 8.1.6 Type 2 driver
• IBM DB/2 7.1 with DB2 7.1 JDBC Application Client
• MS SQL Server 2000 with Merant SequeLink DataDirect 5.0

Ensure the Third Party Database Driver is Registered

On UNIX, if during installation the application server, either "Typical" or "Express" installation options were selected, the Third Party
database driver will not be registered in the application server. If you are unsure as whether or not the client driver was registered, use
the application server's Administrative Tool to determine status of JDBC drivers.

Start the Admin Tool

1. Start the Admin Tool

 

<application server install path>/ias/bin/ksvradmin
 

2. Connect to your application server instance by selecting File->New->Server. Click on Localhost to specify the default connection settings. Enter the application server's administrator's password and click on OK.
3. Click on the Database button and expand the server name (default name of iAS1) to see the database driver settings.
4. If you do not see the driver listed in the External JDBC Drivers folder then you will need to register the Third Party driver in the application server. Go to the next section to register the driver.

Register a Third Party JDBC Driver

1. Register the JDBC Driver with the Application Server
2. Register the JDBC Data Source for the BLOB Application
3. Restart the Application Server

 

Vendor	Driver Name	Classpath example	Native Library Location example
Oracle	oracle.jdbc.driver.OracleDriver	c:\orant\jdbc\lib\classes12.zip	c:\orant\bin
Merant	com.merant.sequelink.jdbc.SequeLinkDriver	c:\Merant\slclient\driver\lib\sljc.jar; c:\Merant\slclient\driver\lib\sljcx.jar
IBM DB/2	COM.ibm.db2.jdbc.app.DB2Driver	c:\DB2\sqllib\java\db2java.zip	c:\DB2\sqllib\bin

See the iPlanet Application Server SP3 Release Notes for a complete description of registering third party JDBC drivers in the application server. The basic steps are as follows:

UNIX:

Execute the db_setup.sh script to register a third party JDBC driver.

a) Enter the application server installation root directory:

Please enter the iAS installation root directory:
/usr/iplanet/ias6

b) Select option 2, Third Party JDBC Drivers

Do you want to use third party JDBC drivers or native drivers.
1. Native drivers
2. Third party jdbc drivers
To accept the default shown in brackets, press the Enter key.

Select the component you want to install (1/2) [1]:
(SELECT OPTION 2 FOR JDBC )

c) Enter a logical name for the driver. This name must be supplied in the next step when configuring the datasource XML file.

d) Enter the driver class name.

e) Enter the fully qualified path of the driver JAR or ZIP file.

f) Enter the path for the driver's native libraries. (Optional: applies to Type 2 drivers only)

Execute the jdbcsetup.exe program to register a third party JDBC driver.

a) Enter a logical name for the driver. This name must be supplied in the next step when configuring the datasource XML file.

b) Enter the driver class name.

c) Enter the fully qualified path of the driver JAR or ZIP file.

d) Enter the path for the driver's native libraries. (Optional: applies to Type 2 drivers only)

Modify the supplied datasource XML files to suit your driver and database connection requirements. The logical driver name you assigned to your third party driver in the driver registration instructions must be the same name as set in the <DRIVER-TYPE> tag of the datasource XML file. See the following sample:

ias-samples/database/blob/src/schema/BlobDB-ora-type2.xml

<ias-resource>
<resource>
<jndi-name>jdbc/samples/database/blob/BlobDB</jndi-name>
<jdbc>
   <driver-type>ora-type2</driver-type>
   <database-url>jdbc:oracle:oci8:@V816_tns_alias</database-url>
   <username>blobsample</username>
   <password>blobsample</password>
</jdbc>
</resource>
</ias-resource>

iasdeploy regdatasource BlobDB-ora-type2.xml

After restarting the application server to pick up the third party database driver and datasource changes, restart your browser and rerun the sample application.

Identify or Create an RDBMS User

To define a new Oracle user:

1. Use SQL Plus to define an Oracle user name (e.g. blobsample).

 

 

SQL > create user blobsample identified by blobsample;

Where the first blobsample is the user name and the second blobsample is the password.

2. Grant connect and resource privileges to the blobsample Oracle user.

 

 

SQL> grant connect, resource to blobsample;

Create the Sample RDBMS Tables

1. Dynamically creates an XML file describing the JDBC datasource.
2. Invokes the application server's iasdeploy regdatasource command to register the data source resource in the application server's registry.
3. Verifies connectivity to the specified database.
4. Creates the tables required by the BLOB application.

UNIX: Create the RDBMS table

Windows: Create the RDBMS table

UNIX: Create the RDBMS table

1. Ensure that the RDBMS enviornment variables are set appropriately. For example, ORACLE_HOME.
2. Edit setup_<rdbms type>.sh. Set the GX_ROOTDIR environment variable to the location of the ias/ directory in your application server installation.

For example,

GX_ROOTDIR=/usr/iplanet/ias6/ias

3. Run setup_<dbname>.sh with the following arguments:

setup_ora.sh <TNS name> <JDBC Driver Name> <dbusername> <dbpassword>
For example using Oracle:
setup_ora.sh iassample ora-816 blobsample blobsample

Where:

<TNS Name> is the Oracle service or TNS name which maps to the appropriate Oracle database instance. In the example above, "iassample" is the Oracle service or TNS name. (This assumes that the Oracle client has been configured to recognize "iassample" as a valid Oracles service/TNS name.)

<JDBC Driver Name> is the name you gave the driver when you registered it.

<dbusername> and <dbpassword> are the Oracle user name and password under which the tables will be created and populated. These are also the values that will be used by the sample application to access the Oracle database.

Since the setup_ora.sh script uses sqlplus, ensure that LD_LIBRARY_PATH includes $ORACLE_HOME/lib.

Windows: Create the RDBMS table

2. Run setup_<rdbms type>.bat with the following arguments:

setup_ora <TNS name> <JDBC Driver Name> <dbusername> <dbpassword>

For example using Oracle:

setup_ora iassample ora-816 blobsample blobsample

Where:

<TNS Name> is the Oracle service or TNS name which maps to the appropriate Oracle database instance. In the example above, "iassample" is the Oracle service or TNS name. (This assumes that the Oracle client has been configured to recognize "iassample" as a valid Oracles service/TNS name.)

<JDBC Driver Name> is the name you gave the driver when you registered it.

<dbusername> and <dbpassword> are the Oracle user name and password under which the tables will be created and populated. These are also the values that will be used by the sample application to access the Oracle database.

Command Line-based Deployment

The pre-built blob.ear file is a Enterprise ARchive file that contains the Web Archive (WAR) file for the BLOB application. Within this JAR file resides the XML deployment descriptor files, application class files and other content required by the application.  The pre-built blob.ear file is configured to not to use the JDBC 2.0 BLOB interface as the majority of drivers do not support this interface.  If you wish to change this then either refer to the GUI-based Deployment instructions or you can repackage the application.

Deploying the pre-built blob.ear file is simple.

1. Go to the root of the BLOB sample directory:

install_dir/ias/ias-samples/database/blob/

install_dir/ias/bin/iasdeploy deployapp blob.ear

The deployment process involves the following operations:

• iasdeploy authenticates against the local application server's administrative server.
• the EAR file is transferred to the administrative server.
• the administrative server begins the registration process:
• parses the EAR file and embedded WAR JAR file
• registers the J2EE application "blob" in the iPlanet Registry within the directory server
• registers the embedded J2EE module (WAR JAR) in the iPlanet Registry within the directory server
• extracts the WAR module to the JAR/ directory.

expands the content of the J2EE modules to the APPS/blob/ directory.

GUI-based Deployment

Two approaches to using the Deployment Tool are described:

Import Pre-existing EAR File to quickly deploy the BLOB application. None of the application assembly steps are covered by this section. On average, this approach will take 15 minutes.

or

Assemble BLOB Application to learn how to use Deployment Tool to assemble and deploy the BLOB application. On average, this approach will take from 30 to 45 minutes.

Import Pre-existing EAR File

Import the EAR File

1. Launch the Deployment Tool.

UNIX:

Execute <application server install path>/ias/bin/deploytool

Windows:

Start->Programs->iPlanet Application Server 6.0->iAS Deployment Tool

• In the startup dialog, select "Browse for more applications" to find the blob.ear file.
• Navigate to ias/ias-samples/database/blob/ and open the blob.ear file.
• Select Component View
• Click on the file name to expand the EAR file.

Modify Environment Settings

1. Expand the blob module.
2. Select DownloadServlet, right click and select Edit Descriptor.
3. Select the Init Params tab.
4. Modify the chunkSize parameter if required.
5. Modify the useBlob parameter if required.
6. Repeat for the UploadServlet.
7. Save the initialization parameter changes by closing the descriptor window.
8. Select the blob module and select File->Save to save the descriptor changes to the EAR file.

Assemble BLOB Application

• Compile Application Sources
• Create blob.war Module
• Assemble blob.ear
• Deploy Application

Compile Application Sources

Create blob.war Module

Identify the Content for WAR File

• In the startup dialog, select New Web Application (.war file)
• Alternatively, if Deployment Tool is already started, select File -> New.
• Click on Web Application.
• Enter "blob.war" as the archive file name.
• Click on Browse to navigate to the directory <application server install path>\ias\ias-samples\database\blob\assemble\
• Click on OK to exit the dialog window.
• The WAR module appears in the Web Applications pane of the Deployment Tool window.
• Click on Component View to see only the name of the WAR module without the directory path.

• Select the WAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert...)
• Choose the path <application server install path>\ias\ias-samples\database\blob\build\lib\classes\samples\database\blob\servlet
• Click on the double arrows (>>) to move all servlet classes into right side of the dialog window.
• Click on Resolve to determine if any of the included classes depend on classes that are not part of the WAR module.
• Click on Insert to add the classes to the WAR module.
• Click on File View to see the complete list of files added to the module.

• Select the WAR module and right click. Select Insert Files (Alternatively, select the module, select Edit->Insert...)
• Navigate to path <application server install path>\ias\ias-samples\database\blob\src\docroot directory.
• Press Shift key, then select the UploadForm.html file.
• Click on the double arrows (>>) to move these files into right side of the dialog window.
• Click on Resolve to modify the location of these files relative to the root of the WAR file.
• Set the Update Destination Path to blank since the application requires that these files be located at the root of the WAR module. Click on Update to modify the relative location. Click on OK to close the resolve dialog window.

Click on Insert to close the insert dialog window and to add the files to the WAR.

Modify the Initial Parameters of All Servlets

• For each servlet:
• select the servlet, right click and select Edit Descriptor
• click on the Init Params tab and then the New Parameter button to add the parameters in the table below.
• after adding the parameters, click on the X in the upper right hand corner of the descriptor window to close the descriptor and save the changes.
• After changing both servlets, select the WAR file, and select File->Close to save and close the WAR file.
• Reopen the WAR file by selecting File->Open.
• Click on Component View to see the renamed beans

 

Parameter Name	Value
chunkSize	10240
useBlob	false

N.B.  The the chunkSize is in bytes and can be varied as desired to see if it improves the streaming of the data. useBlob can be true or false.  Currently you can only set this to true for Oracle or Informix.

Modify Web Application Descriptor

In the References Tab, enter the following data under the References to Resource Factories:

 

Resource Name	Resource Class	Authorization	JNDI Name
BlobDataSource	javax.sql.DataSource	Container	jdbc/samples/database/blob/BlobDB

 

Servlet Name	URL Pattern
UploadServlet	/upload
DownloadServlet	/download/*

Save and close blob.war

• Before closing the WAR file, you might find it useful to double check your settings against the previous instructions.
• Select the WAR module in the Web Applications window.
• Select File->Close to save and close the blob.war file.

Assemble blob.ear

• In the startup dialog, select New J2EE Application (.ear file)
• Alternatively, if Deployment Tool is already started, select File -> New.
• Click on J2EE Application.
• Enter "blob.ear" as the archive file name.
• Click on Browse to navigate to the directory <application server install path>\ias\ias-samples\database\blob\assemble\
• Click on OK to exit the dialog window.
• The EAR file appears in the J2EE Applications pane of the Deployment Tool window.
• Click on Component View to see only the name of the EAR without the directory path.

• Select the blob EAR entry.
• Right click, select Insert Files.
• Navigate to the <application server install path>\ias\ias-samples\database\blob\assemble\ directory.
• Select the WAR file.
• Click on the double arrows (>>) to move this file into right side of the dialog window.
• Click on Resolve to modify the location of this file relative to the root of the EAR file.
• Select the file.
• Set the Update Destination Path to blank since the J2EE module should appear at the root of the EAR file. Click on Update to modify the relative location. Click on OK to close the resolve dialog window.
• Click on Insert to close the insert dialog window and to add the file to the EAR.

Next, we need to set the context root of the web application. This value will appear in URLs that access web application components. For example, in the URL http://localhost/NASApp/blob/upload the "blob" value is the context root of the web application.

• Select WAR module, right click and select Edit Descriptor
• Set the Context Root to "blob".
• Close the descriptor by clicking on the X in the upper right hand corner of the descriptor window. Click on Yes when asked to save the changes.

• Select the EAR file in the J2EE Applications window.
• Select File->Close to save and close the EAR file

Deploy the Application

If you followed the assembly instructions, then blob.ear is opened in Deployment Tool. If you opened the pre-existing EAR file, you are working with <application server install path>\ias\ias-samples\blob\blob.ear. If you are following the "Create EAR File from Scratch" instructions, you are modifying <application server install path>\ias\ias-sample\database\blob\assemble\blob.ear.

If you entered all deployment information manually, you can skip the following steps 1 to 3, because you have entered this information already.

1. Select the blob.ear file under the J2EE Application window.

2. Select File -> Deploy

3. If you have not already registered a target application server, do so now by clicking on the Register button. Enter the host name, administrative port number and username/password for the target application server. Otherwise, select a pre-registered target server.

Note: You may authorize additional users to deploy applications to an application server server by using the application server's Administrative Console. See the Security settings tab in the Administrative Console.

5. Click on Deploy to start the deployment process.

6. Now the file transfer and application registration begins. See the Deploy tab for the status of the deployment. The deployment may take several minutes to complete. Once the status of the deployment changes to Success, proceed to the next section.

Verifying Registration

1. Start the Application Server Admin Tool

UNIX:

<application server install path>/ias/bin/ksvradmin

Windows:

Start->Programs->iPlanet Application Server->iAS Administration Tool

2. Connect to your application server instance by selecting File->New->Server. Click on Localhost to specify the default connection settings. Enter the application server administrator's password and click on OK.
3. Select the server name (default name of iAS1) and select the Application button in the top right hand corner of the window to see the applications registered in this instance of the application server.
4. You should see several folders for the "blob" J2EE application. The "blob" folder with the world icon represents the web application module.

1. Execute kregedit to start the application server's Registry Editor GUI.
2. Navigate to the SOFTWARE/iPlanet/Application Server/6.0/ portion of the tree.
3. Browse the J2EE-Application/ tree and look for the "blob" application.
4. Expand the "blob" folder and explore this portion of the directory tree.
5. Now open the J2EE-Module/ tree and look for the "blob" web application module entry.
6. Expand the folders and explore their contents.

Running the Application

http://<web server hostname>:<port>/NASApp/blob/download/list

1. After the Download Servlet List page appears click on the Upload Form link to navigate to the HTML page to upload content to the database

2. Either select the Browse button and choose a file, or enter the file name path directly in the text field.

3. Click on the Upload button

4. If all is successful the file will be uploaded to the database.  Select the Repository contents link to see the file in the repository.

5. You can select the filename link to download the content, or on the delete link to remove the file from the repository.

Troubleshooting

In general if a problem is going to occur then it will be in the interaction with the database.  In general the servlet in question will report the problem directly to the browser.

Compiling and Assembling the Application

To rebuild the entire sample from scratch, you can simply execute:

build all

On UNIX, you might need to modify your PATH to ensure that install_dir/ias/bin is included to pickup the build script.

Copyright (c) 2001 Sun Microsystems, Inc. All rights reserved.