Oracle Berkeley DB Java Edition
Getting Started with
Berkeley DB Java Edition
Release 3.3
.
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/jeoslicense.html
Oracle, Berkeley DB, Berkeley DB Java Edition 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=273
Published 6/4/2008
TableofContents
Preface ..................................................................................................... vi
Conventions Used in this Book ................................................................... vi
For More Information ....................................................................... vi
1. Introduction to Berkeley DB Java Edition ......................................................... 1
Features .............................................................................................. 1
DPL Features .................................................................................. 3
Base API Features ............................................................................ 4
Which API Should You Use? ................................................................. 4
The JE Application .................................................................................. 5
Database Environments ..................................................................... 5
Key-Data Pairs ................................................................................ 5
Storing Data ................................................................................... 6
Storing Data in the DPL ............................................................... 6
Storing Data using the Base API ..................................................... 6
Duplicate Data ................................................................................ 7
Replacing and Deleting Entries ............................................................. 7
Secondary Keys ............................................................................... 8
Using Secondaries with the DPL ..................................................... 8
Using Secondaries with the Base API. .............................................. 8
Transactions .................................................................................. 9
JE Resources .................................................................................. 9
Application Considerations ............................................................... 10
JE Backup and Restore ........................................................................... 10
JCA Support ........................................................................................ 11
JMX Support ........................................................................................ 11
Getting and Using JE ............................................................................. 12
JE Exceptions ...................................................................................... 12
Six Things Everyone Should Know about JE Log Files ........................................ 13
2. Database Environments .............................................................................. 14
Opening Database Environments ................................................................ 14
................................................................................................. 15
Configuring a Shared Cache for Multiple Environments ............................... 16
Closing Database Environments ................................................................. 17
Environment Properties .......................................................................... 18
The EnvironmentConfig Class ............................................................. 18
EnvironmentMutableConfig ................................................................ 19
Environment Statistics ............................................................................ 20
Database Environment Management Example ................................................ 21
I. Programming with the Direct Persistence Layer ................................................. 24
3. Direct Persistence Layer First Steps ........................................................ 25
Entity Stores ................................................................................. 25
Opening and Closing Environments and Stores .................................. 26
Persistent Objects .......................................................................... 27
Saving a Retrieving Data ................................................................... 28
4. Working with Indices .......................................................................... 30
Accessing Indexes ........................................................................... 30
Page iiGetting Started with JE6/4/2008
Accessing Primary Indices ........................................................... 30
Accessing Secondary Indices ........................................................ 30
Creating Indexes ............................................................................ 31
Declaring a Primary Indexes ........................................................ 31
Declaring Secondary Indexes ....................................................... 32
Foreign Key Constraints ............................................................. 33
5. Saving and Retrieving Objects ............................................................... 35
A Simple Entity Class ....................................................................... 35
SimpleDA.class .............................................................................. 36
Placing Objects in an Entity Store ....................................................... 37
Retrieving Objects from an Entity Store ................................................ 40
Retrieving Multiple Objects ............................................................... 42
Cursor Initialization .................................................................. 42
Working with Duplicate Keys ....................................................... 43
Key Ranges ............................................................................ 44
Join Cursors .................................................................................. 45
Deleting Entity Objects .................................................................... 47
Replacing Entity Objects .................................................................. 47
6. A DPL Example .................................................................................. 49
Vendor.java .................................................................................. 49
Inventory.java ............................................................................... 51
MyDbEnv ...................................................................................... 53
DataAccessor.java .......................................................................... 55
ExampleDatabasePut.java ................................................................. 56
ExampleInventoryRead.java .............................................................. 60
II. Programming with the Base API .................................................................... 65
7. Databases ....................................................................................... 66
Opening Databases ......................................................................... 66
Deferred Write Databases .......................................................... 67
Temporary Databases ................................................................ 70
Closing Databases .................................................................... 71
Database Properties ........................................................................ 72
Administrative Methods .................................................................... 73
Database Example .......................................................................... 75
8. Database Records .............................................................................. 78
Using Database Records .................................................................... 78
Reading and Writing Database Records ................................................. 80
Writing Records to the Database .................................................. 80
Getting Records from the Database ............................................... 81
Deleting Records ..................................................................... 83
Data Persistence ..................................................................... 83
Using the BIND APIs ......................................................................... 84
Numerical and String Objects ...................................................... 84
Serializable Complex Objects ...................................................... 86
Usage Caveats .................................................................. 87
Serializing Objects ............................................................. 87
Deserializing Objects .......................................................... 90
Custom Tuple Bindings .............................................................. 91
Using Comparators .......................................................................... 94
Page iiiGetting Started with JE6/4/2008
Writing Comparators ................................................................. 95
Setting Comparators ................................................................. 95
Database Record Example ................................................................. 97
9. Using Cursors .................................................................................. 108
Opening and Closing Cursors ............................................................. 108
Getting Records Using the Cursor ....................................................... 109
Searching for Records .............................................................. 111
Working with Duplicate Records .................................................. 114
Putting Records Using Cursors ........................................................... 116
Deleting Records Using Cursors ......................................................... 118
Replacing Records Using Cursors ........................................................ 119
Cursor Example ............................................................................ 120
10. Secondary Databases ....................................................................... 125
Opening and Closing Secondary Databases ............................................ 126
Implementing Key Creators ............................................................. 128
Secondary Database Properties ......................................................... 131
Reading Secondary Databases ........................................................... 131
Deleting Secondary Database Records ................................................. 132
Using Secondary Cursors ................................................................. 133
Database Joins ............................................................................. 134
Using Join Cursors .................................................................. 135
JoinCursor Properties .............................................................. 137
Secondary Database Example ........................................................... 138
Opening Secondary Databases with MyDbEnv .................................. 139
Using Secondary Databases with ExampleInventoryRead ..................... 142
III. Administering JE Applications .................................................................... 146
11. Backing up and Restoring Berkeley DB Java Edition Applications ................... 147
Databases and Log Files .................................................................. 147
Log File Overview ................................................................... 147
Cleaning the Log Files .............................................................. 148
The BTree ............................................................................ 148
Database Modifications and Syncs ................................................ 148
Normal Recovery .................................................................... 149
Performing Backups ....................................................................... 149
Performing a Hot Backup .......................................................... 149
Performing an Offline Backup .................................................... 149
Using the DbBackup Helper Class ................................................ 150
Performing Catastrophic Recovery ..................................................... 151
Hot Standby ................................................................................ 152
12. Administering Berkeley DB Java Edition Applications ................................. 154
The JE Properties File .................................................................... 154
Managing the Background Threads ..................................................... 154
The Cleaner Thread ................................................................ 155
The Checkpointer Thread ......................................................... 155
Sizing the Cache ........................................................................... 155
The Command Line Tools ................................................................ 156
DbDump .............................................................................. 157
DbLoad ............................................................................... 158
DbVerify .............................................................................. 160
Page ivGetting Started with JE6/4/2008
