Getting Started with Berkeley DB Java Edition . Makers of Berkeley DB Legal Notice This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license, visit http://www.sleepycat.com/download/cd/commonsdeed.html or send a letter to: Creative Commons 559 Nathan Abbott Way Stanford, California 94305 USA The text and example code included in this document are distributed under the Creative Commons license. Sleepycat Software, Berkeley DB, Berkeley DB XML and the Sleepycat logo are trademarks or service marks of Sleepycat Software, Inc. All rights to these marks are reserved. No third-party use is permitted without the express prior written consent of Sleepycat Software, Inc. 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 write to <[email protected]>. Published 06/10/2004 Table of Contents Preface ............................................................................................... v Conventions Used in this Book ............................................................. v 1. Introduction to Berkeley DB Java Edition ................................................... 1 Features ....................................................................................... 1 The JE Application ........................................................................... 3 Databases and Database Environments ............................................ 3 Database Records ...................................................................... 4 Putting and Getting Database Records ............................................. 4 Duplicate Data ......................................................................... 4 Replacing and Deleting Entries ...................................................... 4 Secondary Databases .................................................................. 5 Transactions ............................................................................ 5 JE Resources ............................................................................ 6 Application Considerations .......................................................... 7 JE Backup and Restore ...................................................................... 7 Getting and Using JE ........................................................................ 8 JE Exceptions ................................................................................. 8 2. Database Environments ......................................................................... 9 Opening Database Environments ........................................................... 9 Closing Database Environments .......................................................... 10 Environment Properties .................................................................... 10 The EnvironmentConfig Class ...................................................... 11 EnvironmentMutableConfig ......................................................... 12 Environment Statistics ..................................................................... 13 Database Environment Example .......................................................... 14 3. Databases ....................................................................................... 17 Opening Databases ......................................................................... 17 Closing Databases .................................................................... 18 Database Properties ........................................................................ 19 Administrative Methods .................................................................... 20 Database Example .......................................................................... 22 4. Database Records .............................................................................. 25 Using Database Records .................................................................... 25 Reading and Writing Database Records ................................................. 26 Writing Records to the Database .................................................. 26 Getting Records from the Database ............................................... 27 Deleting Records ..................................................................... 29 Data Persistence ..................................................................... 29 Using the BIND APIs ......................................................................... 30 Numerical and String Objects ...................................................... 30 Serializeable Complex Objects ..................................................... 32 Usage Caveats .................................................................. 33 Serializing Objects ............................................................. 33 Deserializing Objects .......................................................... 36 Custom Tuple Bindings .............................................................. 37 Using Comparators .......................................................................... 41 06/10/2004 Getting Started with JE Page ii Writing Comparators ................................................................. 41 Setting Comparators ................................................................. 42 Database Record Example ................................................................. 43 5. Using Cursors ................................................................................... 55 Opening and Closing Cursors .............................................................. 55 Getting Records Using the Cursor ........................................................ 56 Searching for Records ............................................................... 58 Working with Duplicate Records ................................................... 60 Putting Records Using Cursors ............................................................ 62 Deleting Records Using Cursors ........................................................... 64 Replacing Records Using Cursors ......................................................... 65 Cursor Example ............................................................................. 66 6. Secondary Databases .......................................................................... 70 Opening and Closing Secondary Databases ............................................. 71 Implementing Key Creators ............................................................... 72 Secondary Database Properties ........................................................... 75 Reading Secondary Databases ............................................................ 76 Deleting Secondary Database Entries .................................................... 77 Using Secondary Cursors .................................................................. 78 Database Joins .............................................................................. 79 Using Join Cursors .................................................................... 80 JoinCursor Properties ................................................................ 82 Secondary Database Example ............................................................. 83 Opening Secondary Databases with MyDbEnv .................................... 84 Using Secondary Databases with ExampleInventoryRead ...................... 87 7. Transactions .................................................................................... 91 Enabling and Starting Transactions ...................................................... 92 Committing and Aborting Transactions .................................................. 93 Aborting Transactions ............................................................... 93 Using Autocommit .................................................................... 94 Transactional Cursors ...................................................................... 95 Configuring Dirty Reads .................................................................... 96 Transactions and Concurrency ............................................................ 98 Transactions and Deadlocks ........................................................ 99 Performance Considerations ........................................................ 99 Transactions Example .................................................................... 100 8. Backing up and Restoring Berkeley DB Java Edition Applications ..................... 104 Databases and Log Files .................................................................. 104 Log File Overview ................................................................... 104 Cleaning the Log Files .............................................................. 105 The BTree ............................................................................ 105 Database Modifications ............................................................ 105 Syncs .................................................................................. 106 Normal Recovery .................................................................... 106 Checkpoints .......................................................................... 106 Performing Backups ....................................................................... 107 Performing a Partial Backup ...................................................... 107