This document describes the maintenance release of JDO, to be called JDO 1.0.1.
Since the release of JDO 1.0, several errata and clarifications have been made to the specification, the reference implementation, and technology compatibility kit.
The maintenance release of JDO addresses the updates in all three areas.
Fixed typo in 5.5.6. Changed "The instance loses its JDO Identity and its association with the PersistenceManager." to "The instance retains its JDO Identity and its association with the PersistenceManager."
In 5.4.1 changed the wording regarding field types of application identity key fields to require portable applications to use only primitive, String, Date, and Number types.
In 5.4.1 added a restriction that application object id instances must not have any key fields with a value of null.
Added to 5.6.1 that the PersistenceManager must not hold a strong reference to a persistent-nontransactional instance, so that it may be garbage collected.
In 5.8, clarified that a before image might be created on update depending on the implementation of optimistic verification.
Corrected table 2 for rollback entries; changed the flag that affects the operation from retainValues to restoreValues.
In Figure 13 Note 23, fixed "A persistent-dirty instance transitions to persistent-nontransactional... at rollback when RestoreValues set to true."
Clarified 6.3 to discuss the treatment of Second Class Objects embedded in First Class Objects. SCO instances of PersistenceCapable types have no standard treatment.
In 8.5, fixed missing property javax.jdo.option.ConnectionDriverName in JDOHelper list of standard properties for getPersistenceManagerFactory.
Added new section 9.5 for new security checking for StateManager. The new authorization strategy does not require that the persistence-capable classes be authorized for JDOPermission("setStateManager").
Fixed 10.3 the description of jdoPreClear does not include deleted instances, as these instances do not transition to hollow.
Fixed typos in 11.2, 12.6.5: changed "JDODatastoreException" to "JDODataStoreException"
Inserted new 11.4 to add PersistenceManagerFactory close method.
Added to 12.6 "If the current transaction is active, close() throws JDOUserException."
In 12.6.1, added new methods retrieveAll (Collection, boolean) and retrieveAll (Object, boolean).
In 12.6.1, clarified the description of retrieve.
In 12.6.4, clarified the description of getExtent to throw JDOUserException if the metadata does not require an extent to be maintained.
In 12.6.5, changed code example from aPersistenceManager.getObjectById (pc.getPersistenceManager().getObjectId(pc), validate) to aPersistenceManager.getObjectById (JDOHelper.getObjectId(pc), validate). This avoids using the PersistenceCapable interface from user code.
In 12.6.5, changed the exception thrown by getObjectById to JDOObjectNotFoundException.
In 12.6.6, clarified description of makeTransient to make clear that the persistence manager is not responsible for clearing references to parameter instances to avoid making them persistent by reachability at commit.
In 12.6.6, clarified description of makeTransactional to include throwing JDOUnsupportedOptionException if a parameter is transient but TransientTransactional is not supported.
Fixed typo in 13.4.2. Changed "The retainValues setting currently active is returned." to "The restoreValues setting currently active is returned."
Fixed typo in 13.4.2. Changed "If this flag is set to true, then restoration of persistent instances does not take place after transaction rollback." to "If this flag is set to true, then restoration of persistent instances takes place after transaction rollback."
Corrected 13.4.3 to remove the requirement that Transaction must implement javax.transaction.Synchronization.
In 13.5, changed the behavior of failed optimistic transactions. The commit method throws a JDOOptimisticVerificationException and automatically rolls back the transaction.
Clarified 14.3 that variable declarations each require a type and a name, and there must be separating semicolons only if more than one declaration.
Clarified 14.3 that "candidate instances" are a subset of the candidate collection that are instances of the candidate class or a subset of the candidate class.
Clarified 14.4 that "compile time" refers to "JDOQL-compile time".
Changed 14.5 to state "If the candidates are not specified, then the candidate extent is the extent of instances in the data store with subclasses true."
Clarified 14.6.2 if a cast operation would throw ClassCastException, it is treated the same as a NullPointerException.
Clarified 14.6.5 the semantics of "contains" is "exists". This clarification is needed to provide a rational meaning if the contains clause is negated.
Clarified in 15 that Extents are not managed for instances of embedded fields.
In 15.3, clarified that the iterator method will throw an exception if NontransactionalRead is not supported.
In 17.1, added getFailedObject() and getNestedExceptions() to the description of JDOException.
In 17.1, fixed description of JDOUnsupportedOptionException: "This class is a derived class of JDOUserException. This exception is thrown by an implementation to indicate that it does not implement a JDO optional feature."
In 17.1.9, added new JDOObjectNotFoundException to report instances that cannot be found in the data store.
In 17.1.10, added new JDOOptimisticVerificationException to report optimistic verification failures during commit.
Changed chapter 18 introduction to describe new policy for naming and accessing metadata files.
In 18.3, changed name scoping for persistence-capable-superclass.
Corrected 18.4 to correct an inconsistency with 20.9.6: "null-valued fields throw a JDOUserException when the instance is flushed to the data store and the data store does not support null values."
Clarified in 18.4 that Extents are not managed for instances of embedded fields.
Updated 18.4.1 and 18.4.2 to clarify type name scoping: The type names use Java rules for naming: if no package is included in the name, the package name is assumed to be the same package as the persistence-capable class. Inner classes are identified by the "$" marker.
In 18.6, added DOCTYPE description to describe access to the public DTD at java.sun.com/dtd.
Changed 20.9.6 to correct an inconsistency with 18.4: "null-valued fields throw a JDOUserException when the instance is flushed to the data store and the data store does not support null values."
Changed 20.17 and 20.20.4 to modify security checking for JDOPermission("setStateManager").
Added new JDOPermission("closePersistenceManagerFactory") to check that the caller of PersistenceManagerFactory.close() is authorized.
Corrected Chapter 23 to remove alternative Name (ArgumentListopt) from MethodInvocation nonterminal in the BNF.
Corrected Chapter 23 to remove the exclusive or operator from the BNF.
Removed Appendix B.3 since it no longer reflects reality.
Reference Implementation Updates
Removed methods to access properties MinPool, MaxPool, and MsWait from PersistenceManagerFactory.
Cleaned up application server integration code for transaction completion.
Fixed missing synchronizations in JDOModel class JDOClassImpl.
Changed Model to support DOCTYPE PUBLIC. The RI recognizes and substitutes its own cached copy if the PUBLIC URI specified is the official Sun URI from the java.sun.com/dtd web site, or if the SYSTEM URI is "file:/javax/jdo/jdo.dtd".
Changed Model to implement the new strategy for finding metadata by searching for files in META-INF, WEB-INF, and package directories.
Fixed FOStorePMF to read and write its own fields upon externalization, to support the Create property
Fixed test cases (in package com.sun.jdori.test) that would fail due to the possibility of unordered results.
Fixed initialization issue in Test_ActivateClass createURL that was platform-specific.
Fixed bug in query compiler that would fail to recompile a changed query.
Fixed bug in query constructor that the ignoreCache flag setting is not copied from the PersistenceManager, and in PersistenceManager constructor that the flag is not copied from PersistenceManagerFactory.
Fixed enhancer bug to downcast the result of calling SM.fetchObjectField(int) if the key field is a subclass of java.lang.Object.
Fixed enhancer bug to work correctly with JDK1.4.
Moved the I18NHelper class from javax.jdo to javax.jdo.spi package. Deprecated the former class to avoid backward compatibility problems.
Added public static field JDOPermission CLOSE_PERSISTENCE_MANAGER_FACTORY with a value of JDOPermission("closePersistenceManagerFactory").
Added methods registerAuthorizedStateManagerClass and checkAuthorizedStateManagerClass to JDOImplHelper.
Removed default constructor for JDOPermission; it is not needed.
Implemented new PersistenceManager APIs retrieveAll ( ... , boolean defaultOnly) for Collection and Object.
Implemented new PersistenceManagerFactory close method.
Fixed the bug that getObjectById might throw an exception if it cannot find the pc class for an ObjectId class, because the class is registered but not activated.
Fixed the bug that the model should complain about missing XML metadata at runtime.
Fixed handling of ClassCastExceptions in queries to return false to the "nearest" boolean expression.
Technology Compatibility Kit Updates
Added signature test. This test checks the signature of all classes in package javax.jdo and javax.jdo.spi to verify that they have the correct signature.
Added tests to cover new API functionality.
Fixed bug 4711478 to compare BigDecimal values using compareTo instead of equals.
Fixed bug 4711539 com.sun.jdotck.api.persistencemanager.GetObjectIdClass compares the object id class to FOStore.OID. This test was removed.
Fixed bug 4721611 com.sun.jdotck.api.persistencemanager.ValuesNotRetainedAfterEvictionAndTransactionCompletion is invalid and was removed.
Fixed bug 4721651 com.sun.jdotck.models.fieldtypes.TestArrayCollections.java Support for persistent fields of array types is optionally in JDO (see JDO spec, chapter 6.4.3 Persistent fields). If a JDO implementation supports this feature, the collection returned by PMF.supportedOptions() includes the string "javax.jdo.option.Array". The TCK test TestArrayCollections was changed to check this option and execute the test only for JDO implementations supporting persistent fields of array types.
Fixed bug 4721919 com.sun.jdotck.query.operators contains tests that include Integer.MAX_VALUE and Long.MAX_VALUE as values to store in the datastore. These values cannot be precisely stored in Float or Double fields. The values were changed to values that can be stored exactly.
Fixed 4721969 com.sun.jdotck.query.QueryTest method checkQueryResultWithOrder compares the result of a JDOQL query with the expected result by calling result.equals(expected). There is no guarantee that equals checks the correct ordering of the result. Note, that checkQueryResultWithOrder is called in the case of an JDOQL query with ordering. The method was changed to first check the size to be equal and then do an iteration to compare the result elements.
Fixed 4711481 com.sun.jdotck.api.instancecallbacks.InstanceCallbackClass) defines the jdo method jdoPreClear. The method body accesses the collection relationship field children w/o testing the field being null. So jdoPreClear runs into a NPE, if the field children is not yet loaded. Please note, the enhancer must not modify the code of jdoPreClear, so it is possible that the field is null. This was fixed to avoid accessing the collection field.