This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com [ Team LiB ] • • • • • • Table of Contents Index Reviews Examples Reader Reviews Errata Java Data Objects By David Jordan, Craig Russell Publisher: O'Reilly Pub Date: April 2003 ISBN: 0-596-00276-9 Pages: 380 This book, written by the JDO Specification Lead and one of the key contributors to the JDO Specification, is the definitive work on the JDO API It gives you a thorough introduction to JDO, starting with a simple application that demonstrates many of JDO's capabilities It shows you how to make classes persistent, how JDO maps persistent classes to the database, how to configure JDO at runtime, how to perform transactions, and how to make queries More advanced chapters cover optional features such as nontransactional access and optimistic transactions The book concludes by discussing the use of JDO in web applications and J2EE environments Whether you only want to read up on an interesting new technology, or are seriously considering an alternative to JDBC or EJB CMP, you'll find that this book is essential It provides by far the most authoritative and complete coverage available [ Team LiB ] This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com [ Team LiB ] • • • • • • Table of Contents Index Reviews Examples Reader Reviews Errata Java Data Objects By David Jordan, Craig Russell Publisher: O'Reilly Pub Date: April 2003 ISBN: 0-596-00276-9 Pages: 380 Dedication Copyright Foreword Preface Who Should Read This Book? Organization Software and Versions Conventions Comments and Questions Acknowledgments Chapter An Initial Tour Section 1.1 Defining a Persistent Object Model Section 1.2 Project Build Environment Section 1.3 Establish a Datastore Connection and Transaction Section 1.4 Operations on Instances Section 1.5 Summary Chapter An Overview of JDO Interfaces Section 2.1 The javax.jdo Package Section 2.2 The javax.jdo.spi Package Section 2.3 Optional Features Chapter JDO Architectures Section 3.1 Architecture Within Application JVM Section 3.2 Datastore Access This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Section 3.3 System Architectures with a JDO Application Chapter Defining Persistent Classes Section 4.1 Kinds of Classes and Instances Section 4.2 Java Classes and Metadata Section 4.3 Fields Chapter Datastore Mappings Section 5.1 Mapping Approaches Section 5.2 Relational Modeling Constructs Section 5.3 Modeling Constructs in Java and Relational Models Section 5.4 Mapping Classes to Tables Section 5.5 Mapping a Single-Valued Field to a Column Section 5.6 Identity Section 5.7 Inheritance Section 5.8 References Section 5.9 Collections and Relationships Chapter Class Enhancement Section 6.1 Enhancement Approaches Section 6.2 Binary Compatibility Section 6.3 Enhancement Effects on Your Code Section 6.4 Changes Made by the Enhancer Chapter Establishing a JDO Runtime Environment Section 7.1 Configuring a PersistenceManagerFactory Section 7.2 Acquiring a PersistenceManager Section 7.3 Transactions Section 7.4 Multiple PersistenceManagers Section 7.5 Multithreading Chapter Instance Management Section 8.1 Persistence of Instances Section 8.2 Extent Access Section 8.3 Accessing and Updating Instances Section 8.4 Deleting Instances Chapter The JDO Query Language Section 9.1 Query Components Section 9.2 Creating and Initializing a Query Section 9.3 Changes in the Cache Section 9.4 Query Namespaces Section 9.5 Query Execution Section 9.6 The Query Filter Section 9.7 Ordering Query Results Section 9.8 Closing a Query Chapter 10 Identity Section 10.1 Overview Section 10.2 Datastore Identity Section 10.3 Application Identity Section 10.4 Nondurable Identity Section 10.5 Identity Methods Section 10.6 Advanced Topics Chapter 11 Lifecycle States and Transitions Section 11.1 Lifecycle States Section 11.2 State Interrogation Section 11.3 State Transitions Chapter 12 Field Management This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Section 12.1 Section 12.2 Section 12.3 Section 12.4 Section 12.5 Section 12.6 Transactional Fields null Values Retrieval of Fields Serialization Managing Fields During Lifecycle Events First- and Second-Class Objects Chapter 13 Cache Management Section 13.1 Explicit Management of Instances in the Cache Section 13.2 Cloning Section 13.3 Transient-Transactional Instances Section 13.4 Making a Persistent Instance Transient Chapter 14 Nontransactional Access Section 14.1 Nontransactional Features Section 14.2 Reading Outside a Transaction Section 14.3 Persistent-Nontransactional State Section 14.4 Retaining Values at Transaction Commit Section 14.5 Restoring Values at Transaction Rollback Section 14.6 Modifying Persistent Instances Outside a Transaction Chapter 15 Optimistic Transactions Section 15.1 Verification at Commit Section 15.2 Optimistic Transaction State Transitions Section 15.3 Deleting Instances Section 15.4 Making Instances Transactional Section 15.5 Modifying Instances Section 15.6 Commit Section 15.7 Rollback Chapter 16 The Web-Server Environment Section 16.1 Web Servers Section 16.2 Struts with JDO Chapter 17 J2EE Application Servers Section 17.1 Enterprise JavaBeans Architecture Section 17.2 Stateless Session Beans Section 17.3 Bean-Managed Transactions Section 17.4 Message-Driven Beans Section 17.5 Persistent Entities and JDO Appendix A Lifecycle States and Transitions Appendix B JDO Metadata DTD Appendix C JDO Interfaces and Exception Classes Section C.1 Interfaces Section C.2 Exceptions Appendix D JDO Query Language BNF Section D.1 Parameter Declaration Section D.2 Variable Declaration Section D.3 Import Declaration Section D.4 Ordering Specification Section D.5 Type Specification Section D.6 Names Section D.7 Literal Section D.8 Filter Expressions Appendix E Source Code for Examples Section E.1 The com.mediamania.appserver package Section E.2 The com.mediamania.content package This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Section E.3 The com.mediamania.hotcache package Section E.4 The com.mediamania.store package Colophon Index [ Team LiB ] This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com [ Team LiB ] Dedication To my wife Tina, whose emotional and financial support made this book possible; and to Jennifer and Jeremy, who now think that their daddy has become addicted to his computer —David Jordan To Kathy, Chris, Ali, and Juliana —Craig Russell [ Team LiB ] This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com [ Team LiB ] Copyright Copyright © 2003 O'Reilly & Associates, Inc Printed in the United States of America Published by O'Reilly & Associates, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472 O'Reilly & Associates books may be purchased for educational, business, or sales promotional use Online editions are also available for most titles (http://safari.oreilly.com) For more information, contact our corporate/institutional sales department: (800) 998-9938 or corporate@oreilly.com Nutshell Handbook, the Nutshell Handbook logo, and the O'Reilly logo are registered trademarks of O'Reilly & Associates, Inc Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks Where those designations appear in this book, and O'Reilly & Associates, Inc was aware of a trademark claim, the designations have been printed in caps or initial caps The association between the image of a lagotis and the topic of Java Data Objects is a trademark of O'Reilly & Associates, Inc Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc., in the United States and other countries O'Reilly & Associates, Inc is independent of Sun Microsystems, Inc While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein [ Team LiB ] This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com [ Team LiB ] Foreword Java Data Objects (JDO) is an important innovation for the Java platform At a time when developers were using JDBC almost exclusively for database access, and expert groups from major enterprise vendors were devising the muchtouted Enterprise Java Beans APIs for entity beans and container-managed persistence, Craig Russell and David Jordan had the courage to take a different course With a handful of others, they looked for a simpler way to provide persistence in the Java platform, something that would be both natural and convenient for programmers This book describes the result of their work: JDO The key, unique idea behind JDO is to provide database persistence in Java with a minimum of extra stuff for the programmer to The programmer doesn't need to learn SQL, doesn't need to tediously copy data into and out of their Java objects using JDBC calls, and can use Java classes, fields, and references in a way that is natural to them, without lots of extra method calls and coding that is extraneous to the programmer's focus and intent Even queries can be written using Java predicates instead of SQL In other words, the programmer just writes Java; the persistence part is automatic In addition to this transparent persistence, code written to JDO benefits from binary compatibility across implementations on different datastores JDO can be used with an object/relational mapping, in which JDBC calls are generated automatically to map the data between Java objects and existing relational databases Alternatively, the JDO objects can be stored directly in file pages, providing the functionality and performance of an object-oriented database The hard work on JDO paid off: the idea of transparent persistence has proven quite popular JDO has its own community web site, www.JDOCentral.com, and on enterprise Java discussion sites such as www.TheServerSide.com, developers praise the simplicity and utility of JDO Many developers use JDO as a replacement for entity beans, by using data objects from within session beans Others use JDO as a convenient high-level replacement for JDBC calls in JSP pages or other Java code JDO has come a long way from the JDBC interface I defined in 1995 with Graham Hamilton, and JDO is quite valuable in conjunction with J2EE I can't think of two individuals better qualified to write a book about JDO Craig is the specification lead for the JDO expert group, and Dave was one of the most active members of that group But their qualifications go far beyond that, and JDO was well designed as a result of those qualifications Both have over a decade of experience with issues in programming language persistence, including subtle transaction semantics, different persistence models, relationships between objects, caching performance, interactions between transient and persistent objects, and programming convenience in practice Both had extensive experience with C++ persistence before they applied their experience to Java Both were key members of the Object Data Management Group (http://www.odmg.org) for years And, most importantly, both were developers who appreciated and needed the functionality that JDO provides Craig and Dave have put together a thorough, readable, and useful book I hope you enjoy it as much as I did —Rick Cattell, Deputy Software CTO Sun Microsystems, February 16, 2003 [ Team LiB ] This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com [ Team LiB ] Preface JDO provides transparent persistence of your Java object models in transactional datastores It allows you to define your object model using all the capabilities provided in Java and it handles the mapping of that data to a variety of underlying datastores You not need to learn and understand a different data-modeling language like SQL You will discover that JDO is very easy to use Many development organizations are discovering the significant development productivity advantages that can be realized by using JDO [ Team LiB ] This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com [ Team LiB ] Who Should Read This Book? If you are a Java programmer who writes software that needs to store data beyond the duration of a single Java Virtual Machine (JVM) context, then you should read this book We assume that you already know Java But you don't need to have a lot of knowledge of databases, because JDO insulates you from needing to know much about them Many Java developers have been using Java Database Connectivity (JDBC) to store their data in a database JDBC requires that you learn SQL When you interact with a database via JDBC, you must view your information model from the perspective of the relational data model, which is very different from Java Many developers never attain the advantages of object-oriented programming because they never define an object model for their persistent data Most of the application software becomes very procedural-like code that manages data in the tables of the relational data model With JDO, Java becomes your data model and you only need to deal with instances of your classes when interacting with the database Having just the single data model of Java as the basis of your data management simplifies your development task considerably [ Team LiB ] This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com [ Team LiB ] [SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] Object persistent field object database 2nd 3rd object identity object-model evolution objectid-class attribute 2nd 3rd 4th 5th 6th 7th 8th objectid-class attribute one-to-many relationship one-to-one relationship Optimistic 2nd 3rd 4th 5th 6th 7th 8th 9th 10th OQL OR query operator 2nd ORDER BY ordering column ordering expression ordering specification 2nd 3rd [ Team LiB ] This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com [ Team LiB ] [SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] package package javax.jdo 2nd package javax.jdo.spi 2nd package metadata attribute name parallel transactions partial primary key Password connection-factory property persistence by reachability 2nd persistence-aware class persistence-by-reachability 2nd 3rd 4th 5th persistence-capable persistence-capable-superclass attribute 2nd 3rd persistence-modifier attribute 2nd 3rd 4th 5th PersistenceCapable 2nd 3rd 4th 5th PersistenceManager 2nd 3rd close() 2nd 3rd 4th currentTransaction() 2nd 3rd 4th 5th 6th deletePersistent() 2nd 3rd 4th 5th 6th 7th 8th 9th 10th 11th 12th 13th 14th jdoPreDelete() 2nd deletePersistentAll() 2nd 3rd 4th 5th evict() 2nd 3rd evictAll() 2nd 3rd 4th 5th 6th getExtent() 2nd 3rd getIgnoreCache() 2nd 3rd getMultithreaded() 2nd getObjectById() 2nd 3rd 4th getObjectId() 2nd getObjectIdClass() 2nd getPersistenceManagerFactory() getTransactionalObjectId() 2nd 3rd 4th getUserObject() 2nd interface declaration isClosed() 2nd makeNontransactional() makeNontransactionalAll() 2nd 3rd makePersistent() 2nd 3rd 4th 5th 6th 7th 8th 9th 10th 11th 12th 13th 14th makePersistentAll() 2nd 3rd makeTransactional() 2nd 3rd 4th 5th makeTransactionalAll() 2nd 3rd 4th 5th makeTransient() 2nd makeTransientAll() 2nd 3rd 4th multiple newObjectIdInstance() 2nd 3rd newQuery() 2nd 3rd 4th 5th 6th 7th 8th 9th 10th 11th 12th 13th 14th 15th 16th 17th 18th refresh() 2nd 3rd 4th 5th refreshAll() 2nd 3rd 4th 5th 6th retrieve() 2nd 3rd 4th 5th retrieveAll() 2nd 3rd 4th 5th 6th 7th 8th setIgnoreCache() 2nd 3rd setMultithreaded() 2nd setUserObject() 2nd PersistenceManager per Application pattern PersistenceManager per Request pattern 2nd This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com PersistenceManager per Session PersistenceManager per Transactional Request pattern PersistenceManagerFactory 2nd close() 2nd getConnectionDriverName() 2nd getConnectionFactory() getConnectionFactory2() 2nd getConnectionFactory2Name() 2nd getConnectionFactoryName() 2nd getConnectionURL() 2nd getConnectionUserName() 2nd getIgnoreCache() getMultithreaded() getNontransactionalRead() 2nd getNontransactionalWrite() 2nd getOptimistic() 2nd 3rd 4th getPersistenceManager() 2nd 3rd 4th 5th getProperties() 2nd 3rd getRestoreValues() getRetainValues() 2nd interface declaration setConnectionDriverName() setConnectionFactory() 2nd setConnectionFactory2() 2nd 3rd setConnectionFactory2Name() 2nd setConnectionFactoryName() 2nd setConnectionPassword() 2nd setConnectionURL() 2nd setConnectionUserName() 2nd setIgnoreCache() setMultithreaded() setNontransactionalRead() 2nd setNontransactionalWrite() 2nd setOptimistic() 2nd 3rd setRestoreValues() setRetainValues() 2nd supportedOptions() 2nd 3rd PersistenceManagerFactoryClass 2nd 3rd 4th persistent class persistent instance persistent-clean state 2nd persistent-deleted state 2nd persistent-dirty state 2nd persistent-new state 2nd persistent-new-deleted state 2nd persistent-nontransactional instance 2nd persistent-nontransactional state 2nd 3rd PHP PlugIn polymorphism 2nd 3rd 4th 5th PortNumber connection-factory property preread policy primary key 2nd 3rd 4th 5th 6th 7th primary-key attribute primary-key field 2nd 3rd primary-key attribute printStackTrace() 2nd 3rd private 2nd processRequest() This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com Properties 2nd 3rd protected 2nd provisionally persistent 2nd 3rd public 2nd putfield 2nd [ Team LiB ] This document is created with a trial version of CHM2PDF Pilot http://www.colorpilot.com [ Team LiB ] [SYMBOL] [A] [B] [C] [D] [E] [F] [G] [H] [I] [J] [K] [L] [M] [N] [O] [P] [Q] [R] [S] [T] [U] [V] [W] [X] Query 2nd 3rd close() 2nd closeAll() 2nd compile() 2nd declareImports() 2nd 3rd 4th 5th declareParameters() 2nd 3rd 4th 5th declareVariables() 2nd 3rd 4th execute() 2nd 3rd 4th 5th 6th 7th 8th 9th 10th executeWithArray() 2nd executeWithMap() getIgnoreCache() 2nd getPersistenceManager() 2nd interface declaration setCandidates() 2nd 3rd setClass() 2nd 3rd setFilter() 2nd 3rd setIgnoreCache() 2nd setOrdering() 2nd 3rd query compilation query imports query namespaces query operator ! != & && > >= <