Oracle Berkeley DB
Getting Started with
Berkeley DB
for Java
Release 4.7
.
Legal Notice
This documentation is distributed under an open source license. You may review the terms of this license at:
http://www.oracle.com/technology/software/products/berkeley-db/htdocs/oslicense.html
Oracle, Berkeley DB, and Sleepycat are trademarks or registered trademarks of Oracle. All rights to these marks
are reserved. No third-party use is permitted without the express prior written consent of Oracle.
Java™ and all Java-based marks are a trademark or registered trademark of Sun Microsystems, Inc, in the United
States and other countries.
To obtain a copy of this document's original source code, please submit a request to the Oracle Technology
Network forum at: http://forums.oracle.com/forums/forum.jspa?forumID=271
Published 4/25/2008
TableofContents
Preface ............................................................................................... v
Conventions Used in this Book ............................................................. v
For More Information ................................................................. vi
1. Introduction to Berkeley DB .................................................................. 1
About This Manual ........................................................................... 2
Berkeley DB Concepts ....................................................................... 2
Environments ........................................................................... 2
Key-Data Pairs .......................................................................... 3
Storing Data ............................................................................ 4
Storing Data in the DPL ........................................................ 4
Storing Data using the Base API ............................................... 5
Duplicate Data ......................................................................... 5
Replacing and Deleting Entries ...................................................... 5
Secondary Keys ......................................................................... 6
Using Secondaries with the DPL .............................................. 6
Using Secondaries with the Base API. ........................................ 6
Which API Should You Use? ........................................................... 7
Access Methods ............................................................................... 7
Selecting Access Methods ............................................................ 8
Choosing between BTree and Hash ................................................. 8
Choosing between Queue and Recno ............................................... 9
Database Limits and Portability ............................................................ 9
Exception Handling ......................................................................... 10
Error Returns ................................................................................ 10
Getting and Using DB ...................................................................... 11
2. Database Environments ....................................................................... 12
Opening Database Environments ......................................................... 12
Closing Database Environments .......................................................... 13
Environment Properties .................................................................... 14
The EnvironmentConfig Class ...................................................... 14
EnvironmentMutableConfig ......................................................... 15
I. Programming with the Direct Persistence Layer ........................................... 17
3. Direct Persistence Layer First Steps .................................................. 18
Entity Stores .......................................................................... 18
Opening and Closing Environments and Stores ............................ 19
Persistent Objects ................................................................... 20
Saving a Retrieving Data ............................................................ 22
4. Working with Indices .................................................................... 23
Accessing Indexes .................................................................... 23
Accessing Primary Indices .................................................... 23
Accessing Secondary Indices ................................................. 23
Creating Indexes ...................................................................... 24
Declaring a Primary Indexes ................................................. 24
Declaring Secondary Indexes ................................................. 25
Foreign Key Constraints ....................................................... 26
5. Saving and Retrieving Objects ......................................................... 28
Page iiGetting Started with DB4/25/2008
A Simple Entity Class ................................................................ 28
SimpleDA.class ........................................................................ 29
Placing Objects in an Entity Store ................................................. 30
Retrieving Objects from an Entity Store .......................................... 33
Retrieving Multiple Objects ......................................................... 35
Cursor Initialization ........................................................... 36
Working with Duplicate Keys ................................................. 36
Key Ranges ...................................................................... 38
Join Cursors ........................................................................... 38
Deleting Entity Objects ............................................................. 40
Replacing Entity Objects ............................................................ 40
6. A DPL Example ........................................................................... 42
Vendor.class .......................................................................... 42
Inventory.class ........................................................................ 44
MyDbEnv ............................................................................... 46
DataAccessor.class ................................................................... 48
ExampleDatabasePut.class .......................................................... 49
ExampleInventoryRead.class ....................................................... 54
II. Programming with the Base API ............................................................. 58
7. Databases ................................................................................. 59
Opening Databases ................................................................... 59
Closing Databases .................................................................... 60
Database Properties ................................................................. 61
Administrative Methods ............................................................. 62
Error Reporting Functions ........................................................... 63
Managing Databases in Environments ............................................. 64
Database Example .................................................................... 66
8. Database Records ........................................................................ 69
Using Database Records ............................................................. 69
Reading and Writing Database Records ........................................... 70
Writing Records to the Database ............................................ 71
Getting Records from the Database ........................................ 72
Deleting Records ............................................................... 73
Data Persistence ............................................................... 74
Using the BIND APIs .................................................................. 75
Numerical and String Objects ................................................ 75
Serializable Complex Objects ................................................ 77
Usage Caveats ........................................................... 78
Serializing Objects ...................................................... 78
Deserializing Objects ................................................... 81
Custom Tuple Bindings ........................................................ 82
Database Usage Example ............................................................ 85
9. Using Cursors ............................................................................. 97
Opening and Closing Cursors ....................................................... 97
Getting Records Using the Cursor .................................................. 98
Searching for Records ....................................................... 100
Working with Duplicate Records ........................................... 103
Putting Records Using Cursors .................................................... 105
Deleting Records Using Cursors ................................................... 107
Page iiiGetting Started with DB4/25/2008
Replacing Records Using Cursors ................................................. 108
Cursor Example ..................................................................... 109
10. Secondary Databases ................................................................. 114
Opening and Closing Secondary Databases ..................................... 114
Implementing Key Creators ...................................................... 117
Working with Multiple Keys ................................................. 120
Secondary Database Properties ................................................... 121
Reading Secondary Databases .................................................... 121
Deleting Secondary Database Records ........................................... 122
Using Secondary Cursors .......................................................... 123
Database Joins ...................................................................... 124
Using Join Cursors ............................................................ 125
JoinCursor Properties ........................................................ 128
Secondary Database Example ..................................................... 128
Opening Secondary Databases with MyDbs ............................... 130
Using Secondary Databases with ExampleDatabaseRead ............... 133
11. Database Configuration .............................................................. 137
Setting the Page Size ............................................................... 137
Overflow Pages ............................................................... 137
Locking ......................................................................... 138
IO Efficiency .................................................................. 139
Page Sizing Advice ........................................................... 139
Selecting the Cache Size ........................................................... 140
BTree Configuration ................................................................ 140
Allowing Duplicate Records ................................................. 141
Sorted Duplicates ...................................................... 141
Unsorted Duplicates ................................................... 141
Configuring a Database to Support Duplicates .................... 142
Setting Comparison Functions .............................................. 143
Creating Java Comparators .......................................... 144
Page ivGetting Started with DB4/25/2008
