Table of Contents
Purpose of This Document
Audience
How This Document Is Organized
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
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
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
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
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
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
The Classes Pertaining to Resource Managers
How to Use Them
Getting a DataSource
Shutting Down or Creating a Database
Remote DataSources
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
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
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
Database Locale
Setting a Database's Locale
Finding Out a Database's Locale
SQL Parser Support for Unicode
Other Components
Messages Libraries
|