Skip to main content

skip to main content

developerWorks  >  WebSphere | Open source | Information Management  >

Using IBM Cloudscape V10 with IBM WebSphere Application Server V6

developerWorks
Document options

Document options requiring JavaScript are not displayed

Sample code


Rate this page

Help us improve this content


Level: Introductory

Soloman Barghouthi (soloman@us.ibm.com), Advisory Software Engineer, IBM

26 Jan 2005

This article describes changes and new features in IBM® Cloudscape™ Version 10, also known as the Derby release, and the process of how to configure IBM WebSphere® Application Server to use this new version.

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 codeNew codeDescription
    2300023502Column {0} cannot accept a NULL value.
    2350023505The 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}.
    23L0123505
    2350123503Descr{2} on table {1} caused a violation of foreign key constraint {0} for key {3}. The statement has been rolled back.iption
    23L0223513The check constraint {1} was violated while performing an INSERT or UPDATE on table {0}.
    42X1142622The name {0} is too long. The maximum length is {1}.
    42X1842818Comparisons between {0} and {1} are not supported.
    42X4242821Columns 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.
    42Y1842846Cannot convert types {0} to {1}.
    XJZZZ0A000Feature 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.

You can obtain the new Version 10 JARs from Cloudscape.


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.


Figure 1. Derby directory structure
Figure 1. Derby directory structure

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
      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
      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
      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
      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
      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
      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
      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.
You might need to restart WebSphere Application Server or the deployment manager for the alias to take effect.

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);

    }
}


Figure 9. Define a user-defined data store helper
Figure 9. Define a user-defined data store helper

Figure 10. Define a user-defined data store helper in a network server
Figure 10. Define a user-defined data store helper in a network server


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


Figure 11. Perform EJB deployment from the admin console
Figure 11. Perform EJB deployment from the admin console


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

DescriptionNameSizeDownload method
Derby installation filesderbyInstall.zip10 KBFTP|HTTP
Information about download methods


Resources



About the author

Soloman Barghouthi is an Advisory Software Engineer at the IBM Rochester Lab. Soloman started his career at IBM working as a developer on the San Francisco project, and is currently a developer on the WebSphere Connection Management team. Soloman is a database expert, the Oracle resident, and has deep knowledge in DB2. Soloman is responsible for how Cloudscape and Oracle operate in WebSphere.




Rate this page


Please take a moment to complete this form to help us better serve you.



 


 


Not
useful		Extremely
useful
 


Share this....

digg Digg this story del.icio.us del.icio.us Slashdot Slashdot it!



Back to top