Table of Contents
Page 1 of 1

Table of Contents

About This Document

Purpose of This Document

Audience

How This Document Is Organized

1 After Installing

The Installation Directory

Batch Files and Shell Scripts

Cloudscape and JVMs

Incompatibility Between Pre-1.1.6 and 1.2 Databases

Cloudscape Libraries and Class Path

Upgrades

Recommended Steps Before Upgrading

Upgrading a Database

Synchronization Databases and Upgrades

UNIX-Specific Issues

Configuring File Descriptors

Scripts

2 JDBC Applications and the Cloudscape Technology

Application Development Overview

Cloudscape Basics

Cloudscape JDBC Driver

Cloudscape JDBC Database Connection URL

Cloudscape System

One Cloudscape per System

Booting

Shutting Down the System

Defining the System Directory

The Information (Error) Log

cloudscape.properties

Double-Booting System Behavior

A Cloudscape Database

The Database Directory

Creating, Dropping, and Backing Up Databases

Single Database Shutdown

Storage and Recovery

Log on Separate Device

Database Pages

Database-Wide Properties

Version 3 Database Limitations

Connecting to Databases

Standard Connections--Connecting to Databases in the File System

Within the System

Outside the System Directory

Conventions for Specifying the Database Path

Special Database Access

From the Class Path

From a Jar or Zip File

Examples

Working with the Database Connection URL Attributes

Shutting Down Cloudscape or an Individual Database

Creating and Accessing a Database

Accessing an Existing Database

As the Subprotocol

Using the databaseName Attribute

Turning Off Auto-Commit

Getting a Nested Connection

Providing a User Name and Password

Encrypting a Database When You Create It

Booting an Encrypted Database

Upgrading a Database

Specifying Attributes in a Properties Object

Cloudscape Embedded Basics

Embedded Cloudscape JDBC Driver

Embedded Cloudscape JDBC Database Connection URL

Starting Cloudscape as an Embedded Database

Working with Database Threads in an Embedded Environment

Cloudscape on Small Platforms

3 Deploying Cloudscape Applications

Deployment Issues

Deployment Options

Embedded Deployment Application Overview

Client/Server Deployment Application Overview

Synchronization Application Overview

Choosing a Deployment Option

Deploying Java Classes for Use as Java Data Types

Java Data Type Deployment, Embedded Environment

Java Data Type Deployment, Client/Server Environment

Deployment Cheat Sheets

Deploying Cloudscape in an Embedded Environment

Embedded Systems and Properties

Deploying Client/Server Applications

Deploying Cloudsync Systems

Creating Cloudscape Databases for Read-Only Use

Creating and Preparing the Database for Read-Only Use

Deploying the Database on the Read-Only Media

Transferring Read-Only Databases to Archive (Jar or Zip) Files

Accessing a Read-Only Database in a Zip/Jar

Accessing Databases-in-a-Jar in the Class Path

When Path Is Ambiguous with Databases in File System

When Path Is Ambiguous Because of Databases in Class Path

Read-Only Databases and Upgrading

Databases on Read-Only Media and DatabaseMetaData

Loading Classes from a Database

Class Loading Overview

Signed Jar Files

Create Jar Files for Your Application

Choose Between Database-Level and System-Level Class Loading

Add the Jar File or Files to the Database

Examples

Adding Jar Files

Removing Jar Files

Replacing Jar Files

Enable Database Class Loading with a Property

Force Cloudscape Class Loading for the Application

Class Loading: Database-Side Only vs. Database- and Application-Side

Enabling Cloudscape Class Loading for Database-Side Logic Execution

Class Path Class Loading for Application-Side Logic Execution

Cloudscape Class Loading for Client-Side Logic Execution

Code Your Applications the Way You Normally Would

Dynamic Changes to Jar Files or Database Jar Class Path

Requirements

Notes

4 Using Cloudscape's Java Extensions

Java and SQL-J Integration

Referring to Classes Within SQL-J

Storing Java Objects in Cloudscape Tables

Defining a Column to Store a Java Data Type

Storing Objects in the Column

Cloudscape Database Design Considerations

Retrieving and Updating Objects

Retrieving Objects

Updating Objects

Orderable Java Data Types

Invoking Methods and Accessing Fields

Executing Methods

Refining Search Conditions

Accessing Methods When Storing Subclasses

Invoking Methods on Classes Not Serialized in the Database

Creating an Instance of a Class on the Fly Using Built-in Types

Class Method Invocation and Class Field Access (Static Methods and Fields)

Method Invocation and Dynamic Parameters

Invoking Database-Side JDBC Methods

Other Java-Smart Syntax in SQL-J

Using Methods to Emulate SQL-92 Functions

SQL-J and Java Type Correspondence

Using the Cloudscape Types to Query the System Tables

Getting External Data: Using the Cloudscape Virtual Table Interface

5 Special Cloudscape Programming

Programming Database-Side JDBC Methods

Overview

Database-Side JDBC Methods and Nested Connections

GETCURRENTCONNECTION Built-In Method

current=true attribute

Requirements for Database-Side JDBC Methods Using Nested Connections

Nested Connections and Work Units

Example Method

Invoking the Example Method

Database-Side JDBC Methods Using Non-Nested Connections

Example Method Using New (not Nested) Connection

Invoking the Example Method Using the CALL Command

Database-Side JDBC Methods and SQLExceptions

User-Defined SQLExceptions

Programming Serializable Classes

Requirements for Serialization

Serializable vs. Externalizable

Marking Fields as Transient

Modifying Classes (Java Versioning)

Compatible and Incompatible Changes

Using the serialVersionUID to Indicate Serializable Compatibility

Versioning Mini Tutorial

Other Kinds of Versioning

Serializable Objects and Input/Output Streams

Programming VTIs

Read-Write VTIs

Requirements and Options for Read-Write VTI Classes

Notes on Implementing java.sql.PreparedStatement

What Happens Behind the Scenes During Compilation and Execution of a Read-Write VTI

INSERT Statements

DELETE Statements

SELECT Statements

Read-Only VTIs

Requirements and Options for Read-Only VTI Classes

Deprecation of the getResultSetMetaData Method

Compile Time vs. Execution Time

Information Applicable to Both Read-Write VTIs and Read-Only VTIs

Implementing ResultSet

ResultSet and ResultSetMetaData Methods Used by Cloudscape

Rules for Parameters to VTIs

Constant Parameters

Non-Constant Parameters

Providing Costing Information

Estimating the Cost

Templates for Creating VTIs

Built-In VTIs and Example VTIs

Built-In VTIs

Example VTIs

Programming User-Defined Aggregates

Developing the Java Classes that Perform the Aggregation

Programming Trigger Actions

Trigger Action Overview

Performing Referential Actions

Accessing Before and After Rows

Examples

Triggers and Exceptions

Example of User-Defined SQLException

Exceptions in Triggers Actions

Aborting Statements and Transactions

Transactionally Independent Trigger Actions

Long-Running Trigger Actions

Programming Orderable Classes

Requirements for Orderable Java Data Types

Notes on compareTo Implementation

Notes on Implementing the equals and hashCode Methods

Comparison Operators and Objects of Different Types

One of the Java Data Types is Orderable

Neither Java Data Type Is Orderable

6 Controlling Cloudscape Application Behavior

The JDBC Connection and Transaction Model

Connections

Statements

ResultSets and Cursors

Nested Connections

Transactions

Transactions When Auto-Commit Is Disabled

Using Auto-Commit

Turning Off Auto-Commit

Explicitly Closing Statements, ResultSets, and Connections

Statement vs. Transaction Runtime Rollback

SQL-J and JDBC ResultSet/Cursor Mechanisms

Simple Non-Updatable ResultSets

Updatable Cursors

Requirements for Updatable Cursors

Naming or Accessing the Name of a Cursor

Updatable Cursors and Cloudconnector

Extended Updatable Cursor Example

ResultSets and Auto-Commit

Scrolling Insensitive ResultSets

Locking, Concurrency, and Isolation

Isolation Levels and Concurrency

Configuring Isolation Levels

Lock Granularity

Types and Scope of Locks in Cloudscape Systems

Exclusive Locks

Shared Locks

Update Locks

Lock Compatibility

Scope of Locks

Notes on Locking

Bulk Fetch and Row Locks

Locking Examples

Row-Level Locking, TRANSACTION_READ_COMMITTED

Row-Level Locking, TRANSACTION_SERIALIZABLE and REPEATABLE_READ

Deadlocks

Avoiding Deadlocks

Deadlock Detection

Lock Wait Timeouts

Configuring Deadlock Detection and Lock Wait Timeouts

Debugging Deadlocks

Programming Applications to Handle Deadlocks

Working with Multiple Connections to a Single Database

Deployment Options and Threading and Connection Modes

Multi-User Database Access

Multiple Connections from a Single Application

Working with Multiple Threads Sharing a Single Connection

Pitfalls of Sharing a Connection Among Threads

Reasons for Trying to Share a Connection or Statement Across Threads

Threads Sharing a Statement: A Case Study

Working with Cloudscape SQLExceptions in an Application

Information Provided in SQLExceptions

7 Using Cloudscape as a J2EE Resource Manager

The Classes Pertaining to Resource Managers

How to Use Them

Getting a DataSource

Shutting Down or Creating a Database

Remote DataSources

8 Cloudscape and Security

Security Overview

Features

Configuring Security for Your Environment

Configuring Security in a Client/Server Environment

Configuring Security in an Embedded Environment

Configuring Security in a Synchronization System

Working with User Authentication

Overview

Enabling User Authentication

Defining Users

External Directory Service

LDAP Directory Service

Libraries for LDAP User Authentication

Setting Up Cloudscape to Use Your LDAP Directory Service

Guest Access to Search for DNs

Performance Issues

Windows NT Users

Restrictions

NIS Directory Service Plus (NIS+)

Libraries for NIS Directory Service Plus User Authentication

Configuring Cloudscape for NIS+ User Authentication

JNDI-Specific Properties for External Directory Services

User-Defined Class

Built-in Cloudscape Users

Database-Level Properties

System-Level Properties

Properties Summary

Programming Applications for Cloudscape User Authentication

Programming the Application to Provide the User and Password

Login Failure Exceptions

Users and Authorization Identifiers

Authorization Identifiers, User Authentication, and User Authorization

User Names and Schemas

Exceptions

User Authorization

Setting User Authorization

Database or System Access

Setting the Default Access Mode

Setting the Access Mode for Particular Users

Notes on User Authorization

Exceptions

About Read-Only and Full Access

Examples

Encrypting Databases on Disk

Overview

Requirements for Cloudscape Encryption

Working with Encryption

Encrypting Databases on Creation

Creating the Boot Password

Specifying an Alternate Encryption Provider

Specifying an Alternate Encryption Algorithm

Booting an Encrypted Database

Changing the Boot Password

SSL

Signed Jar Files

Notes on the Cloudscape Security Features

User Authentication and Authorization Examples

Client/Server Environment

Single-User, Embedded Environment

Extended Example

Synchronization Environment

9 Developing Tools and Using Cloudscape with an IDE

Working with Metadata for Java Data Types

Offering Connection Choices to the User

The DriverPropertyInfo Array

databaseName

Example

Storing DatabaseMetaData Queries

Using Cloudscape with IDEs

IDEs and Multiple JVMs

About the RmiJdbc Driver

Using the RmiJdbc Driver in an IDE

10 SQL-J Tips

Performing Case-Insensitive Sorts

Retrieving the Database Connection URL

Using java.lang Methods as Functions

Getting Methods to Look and Work More Like Stored Procedures

Using Cloudscape-Supplied Methods to Work with Bits

Working with Arrays

Managing External Resources

Accessing Data from Another DBMS with Cloudscape's VTI

Working with Date/Time Formats

Supplying a Parameter Only Once

Defining a Sequence-Number Column

Generating Unique Keys

Using Literals to Save Keystrokes

Integrating External Libraries

Using Third-Party Tools

Accessing and Modifying System Properties

Tricks of the VALUES Clause

Multiple Rows

Mapping Column Values to Return Values

Creating Empty Queries

Inserting a Row of Nulls

Forcing Garbage Collection and Finalization

Using a Derived Table to Avoid Redundant Method Calls

Using RunTimeStatistics to Get an Approximate Row Count for a Table

Appendix A Mapping of Functions to java.lang Methods

Appendix B Localizing Cloudscape

Database Locale

Setting a Database's Locale

Finding Out a Database's Locale

SQL Parser Support for Unicode

Other Components

Messages Libraries

Index