Introduction

This article highlights some of the important changes in IBM Cloudscape Version 10, also known as the Derby release. Among the notable new changes is that Cloudscape V10 is now an IBM DB2® compatible database. In addition, some important changes affect the configuration of IBM WebSphere Application Server V6. These changes will be the focus of this article.

As of the writing of this article, the IBM WebSphere Application Server V6 software support site does not explicitly list Cloudscape V10 as one of its supported databases (due to the late announcement of the Cloudscape release). However, Cloudscape V10 should be supported by WebSphere Application Server V6 as an "Other Configuration", as defined by the support statement. Cloudscape V10 is expected to be officially supported in an upcoming release of WebSphere Application Server.

Back to top

Changes that affect WebSphere Application Server configuration

Several changes have been made to Cloudscape V10 that affect how WebSphere Application Server V6 should be configured.

New package names

Cloudscape V10 has new package names that will enable it to coexist in the same WebSphere Application Server environment with a previous version of Cloudscape (such as, Cloudscape 5.1.60). The new package names have been changed from com.ibm.db2j.* to org.apache.derby.*. The new package names are:

org.apache.derby.drda
org.apache.derby.jdbc
org.apache.derby.tools

Other naming changes include:

• db2j.properties file has been changed to derby.properties
• db2j.system.home has been changed to derby.system.home.

DB2 compatibility

Cloudscape V10 is a DB2 compatible database, with compatibility in the following areas:

• Data Definition Language (DDL) and Data Manipulation Language (DML)
  Cloudscape V10 DDL and DML are subsets of DB2's.
• Error codes and SQLStates
  The most common SQLStates and error codes have been changed in Cloudscape V10 to match those of DB2. For example:

  Previous code	New code	Description
  23000	23502	Column {0} cannot accept a NULL value.
  23500	23505	The statement was aborted because it would have caused a duplicate key value in a unique or primary key constraint or unique index identified by {0} defined on {1}.
  23L01	23505
  23501	23503	Descr{2} on table {1} caused a violation of foreign key constraint {0} for key {3}. The statement has been rolled back.iption
  23L02	23513	The check constraint {1} was violated while performing an INSERT or UPDATE on table {0}.
  42X11	42622	The name {0} is too long. The maximum length is {1}.
  42X18	42818	Comparisons between {0} and {1} are not supported.
  42X42	42821	Columns of type {0} cannot hold values of type {1}. This error can occur with user-defined classes if they are not in the class path.
  42Y18	42846	Cannot convert types {0} to {1}.
  XJZZZ	0A000	Feature not implemented: {0}.

  Users will benefit greatly from the standards-based features in Cloudscape V10, since it enables users to develop applications against Cloudscape V10 in a development environment, deploy in a small-to-medium-sized production environment, and then run against DB2 in the enterprise environment.

See Migrating IBM Cloudscape for a complete list of changes between Cloudscape V5.1 and Cloudscape V10.

Back to top

Install Cloudscape V10 in the WebSphere Application Server V6 environment

To install Cloudscape V10 in a WebSphere Application Server V6 environment:

1. Unzip the provided derbyInstall.zip download file into the WAS_HOME directory (where WebSphere Application Server is installed, for example c:\Program Files\WebSphere\AppServer), as follows:
   • Copy the derbyInstall.zip file to ${WAS_HOME}.
   • Enter the command cd ${WAS_HOME}.
   • Unzip derbyInstall.zip.
2. Download Cloudscape V10 JAR files into ${WAS_HOME}\derby\lib, as follows:
   • Locale files go to ${WAS_HOME}\derby\lib\locales.
   • db2jcc.jar goes to ${WAS_HOME}\derby\lib\otherJars.
   • derbytools.jar, derby.jar, derbynet.jar, and db2jcc_license_c.jar go to ${WAS_HOME}\derby\lib.
3. Modify ${WAS_HOME}\bin\setupCmdLine.bat/sh and add:
   • For Windows®: SET DERBY_HOME=%WAS_HOME%\derby.
   • For UNIX® or Linux®: DERBY_HOME="$WAS_HOME"/derby.
   The resulting directory structure should like similar to Figure 1.

You should now be able to run the same commands in Cloudscape V10 that you did in Cloudscape 5.1 (such as, ij, startNetworkServer, stopNetworkServer, and so on). Be aware that cview.sh/bat does not appear, as Cloudscape has ended support for this tool.

Back to top

Configure WebSphere Application Server V6 for Cloudscape V10

Configuring WebSphere Application Server V6 to run against Cloudscape Version 10, you first need to configure a Java™ Database Connectivity (JDBC) provider for the new version of Cloudscape, then configure data sources for the new JDBC provider.

Configure a JDBC provider for Cloudscape V10

As always, the first step for running against a database is to configure a JDBC provider for the application server. There are three different providers that can be configured in WebSphere Application Server V6 for Cloudscape V10:

1. Configure a JDBC provider for Cloudscape V10
   1. Log on to the WebSphere administrative console (at http://localhost:9060/ibm/console).
   2. Select Resources => JDBC Providers, then Scope => Server. Click Apply then New (Figure 2).
      Figure 2. Admin console
      
      
   3. On the New JDBC provider dialog (Figure 3), select the following values:
      • Step 1: Cloudscape
      • Step 2: Cloudscape JDBC Provider
      • Step 3: Connection pool data source
      then select Next.
      Figure 3. New JDBC provider
      
      
   4. On the Embedded JDBC provider dialog (Figure 4), enter values for the following fields:
      • Name (optional but recommended)
      • Description (optional)
      • Class path (required): must point to the new CloudscapeV10 JAR file (such as, ${WAS_INSTALL_ROOT}/derby/lib/derby.jar)
      • Implementation class: enter org.apache.derby.jdbc.EmbeddedConnectionPoolDataSource
      then select Apply.
      Figure 4. Cloudscape V10 Embedded JDBC Provider
      
      
2. Configure a Cloudscape embedded JDBC provider (XA)
   1. Log on to the WebSphere administrative console (at http://localhost:9060/ibm/console).
   2. Select Resources => JDBC Providers, then select scope. Click Apply then New.
   3. On the New JDBC provider dialog (Figure 5), select the following values:
      • Step 1: Cloudscape
      • Step 2: Cloudscape JDBC Provider
      • Step 3: XA data source
      then select Next.
      Figure 5. New JDBC provider
      
      
   4. On the next dialog (Figure 6), enter values for the following fields:
      • Name (optional but recommended)
      • Description (optional)
      • Class path (required): must point to the new Cloudscape V10 JAR file (such as, ${WAS_INSTALL_ROOT}/derby/lib/derby.jar)
      • Implementation class: enter org.apache.derby.jdbc.EmbeddedXADataSource
      then select Apply.
      Figure 6. JDBC provider configuration
      
      
3. Configure a Cloudscape Network Server JDBC provider
   1. Log on to the WebSphere administrative console (at http://localhost:9060/ibm/console).
   2. Select Resources => JDBC Providers, then select scope. Click Apply then New.
   3. On the New JDBC provider dialog (Figure 7), select the following values:
      • Step 1: Cloudscape
      • Step 2: Cloudscape Network Server Using Universal JDBC Driver
      • Step 3: connection pool data source
      then select Next.
      Figure 7. New JDBC provider
      
      
   4. On the next dialog (Figure 8), modify the description (optional), then replace the db2j.jar entry in the Class path with derby.jar, which is the new Cloudscape V10 JAR. The value of Class path should then look something like:

      ${DB2UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc.jar ${CLOUDSCAPE_JDBC_DRIVER_PATH}/otherJars/db2jcc.jar ${WAS_INSTALL_ROOT}/derby/lib/derby.jar ${UNIVERSAL_JDBC_DRIVER_PATH}/db2jcc_license_cu.ja

      Select Apply.
      Figure 8. JDBC provider configuration
      
      

Configure data sources for the new JDBC provider

To create and define a WebSphere data source:

1. Log on to the WebSphere Application Server admin console at http://localhost:9060/admin.
2. Select Resources => JDBC providers, then scope and Apply.
3. Select the JDBC provider created above.
4. Under "Additional Properties", select Data sources => New to create a new data source.
5. The most important section in the page that displays is the "Data store helper class name" where a user-defined data store helper needs to be created and defined, as described below.
6. Define the component-managed or container-managed authentication alias, as your application requires, as described below. An alias definition is only required if running Cloudscape V10 Network Server framework.
7. Select OK and Save.

Create an authentication alias

To create an authentication alias (if none are defined in the drop-down list):

1. From the WebSphere Application Server admin console, select Security => Global security => JAAS Configuration => J2C Authentication Data => New.
2. Enter values for the Alias, User ID, and Password fields.
3. Select OK, then Save the configuration.

Create a new data store helper

Since some of the exception errorCodes and SQLStates have changed in Cloudscape V10, a user-defined data store helper needs to be created and defined in WebSphere Application Server to include the new mapping for StaleConnectionExceptions and DuplicateKeyExceptions. To create a new user-defined data store helper:

1. Create a class that extends com.ibm.websphere.rsadapter.CloudscapeDataStoreHelper (Listing1) or com.ibm.websphere.rsadapter.CloudscapeNetworkServerDataStoreHelper (Listing 2).
2. Compile the newly created DataStoreHelper class(es). You will need the following JAR files in your classpath to compile them (all located in {WAS_HOME}/lib):
   • utils.jar
   • j2ee.jar
   • rsaexternal.jar.
3. Create a JAR file of the compiled class(es) and put them in {WAS_HOME}/lib/ext.

Now that the data store helpers have been created, you need to configure them in the WebSphere data source created above. See Figure 9 or, in the case of NetworkServer, Figure 10, for an example of how they get set.

Listing 1. Embedded (xa and non-xa) user-defined helper

package myCompany.helper;

import java.util.Properties;
import com.ibm.websphere.ce.cm.DuplicateKeyException;
import com.ibm.websphere.rsadapter.CloudscapeDataStoreHelper;

public class MyDerbyDataStoreHelper extends CloudscapeDataStoreHelper
{
    //static final long serialVersionUID = ;
    //to be generated by user

    public MyDerbyDataStoreHelper(Properties props)
    {
        super(props);

        java.util.HashMap myErrorMap = new java.util.HashMap(3);
        myErrorMap.put("23505", DuplicateKeyException.class);
        myErrorMap.put("23500", Void.class);
        myErrorMap.put("23L01", Void.class);
        setUserDefinedMap(myErrorMap);
    }
}

Listing 2. Network Server user-defined helper

package myCompany.helper;

import java.util.Properties;
import com.ibm.websphere.ce.cm.DuplicateKeyException;
import com.ibm.websphere.ce.cm.StaleConnectionException;
import com.ibm.websphere.rsadapter.CloudscapeNetworkServerDataStoreHelper;

public class MyDerbyNetworkServerDataStoreHelper extends CloudscapeNetworkServerDataStoreHelper
{
    //This value should change only if the class evolves to an incompatible class.
    //static final long serialVersionUID = ;
    //to be generated by user


    public MyDerbyNetworkServerDataStoreHelper(Properties props)
    {
        super(props);
        java.util.HashMap myErrorMap = new java.util.HashMap(4);
        myErrorMap.put("23505", DuplicateKeyException.class);
        myErrorMap.put("23500", Void.class);
        myErrorMap.put("23L01", Void.class);
        myErrorMap.put(new Integer(-4499), StaleConnectionException.class);

        setUserDefinedMap(myErrorMap);

    }
}

Back to top

Deploy a Cloudscape V10 application

When deploying an application that uses Cloudscape V10 in WebSphere Application Server V6, you must select DB2UDB_V81 as the database type. This is the only difference between deploying an application using Cloudscape V10 versus Cloudscape 5.1. Figure 11 shows how you can do this from the admin console. (Since you are deploying with DB2UDB_V81 instead of specifically to a Cloudscape V10 database schema, it is possible that a limitation may prevent the generated deployed code from running with Cloudscape V10 in CMP (container managed persistence) cases only. Note, however, that the possibility of such a problem is small, since Cloudscape generated code is very close to DB2's generated code.)

Back to top

Conclusion

This article described some of the major changes made in IBM Cloudscape Version V10 that affect WebSphere Application Server, explained how to install this new version in WebSphere Application Server V6.0, how to configure WebSphere Application Server so that it can run with Cloudscape V10, and how to deploy an application to run in Cloudscape V10. Most of the information described in this article applies only to WebSphere Application Server V6.

Back to top

Download

Description	Name	Size	Download method
Derby installation files	derbyInstall.zip	10 KB	FTP|HTTP

Information about download methods

Resources

• Cloudscape Version 10.0: A technical overview
  
  
• WebSphere Application Server supported hardware and software
  
  
• WebSphere Application Server clarification of configurations support
  
  
• IBM developerWorks DB2 Cloudscape
  
  
• Migrating IBM Cloudscape
  
  
• To learn more, visit the developerWorks WebSphere Application Server zone for technical documentation, how-to articles, education, downloads, product information, technical support resources, and more.
  
  
• Browse for books on these and other technical topics.
  
  
• WebSphere forums. Product-specific forums where you can ask questions and share your opinions with other WebSphere users.
  
  
• developerWorks blogs. Ongoing, free-form columns by software experts, with space for you to add your comments.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Changes that affect WebSphere Application Server configuration
• Install Cloudscape V10 in the WebSphere Application Server V6 environment
• Configure WebSphere Application Server V6 for Cloudscape V10
• Deploy a Cloudscape V10 application
• Conclusion
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: DB2 Enterprise
• Demo: Create an electronic form solution with DB2 pureXML and Lotus Forms
• Community: DB2
• Buy: DB2 Enterprise

Dig deeper into WebSphere on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers