**************** REVISION HISTORY ******************** --- THIS FILE CONTAINS VERY IMPORTANT INFORMATION --- This is version v3.12 built December 20, 2003 of the Visual Business Sight Framework (VBSF). Trial versions are limited to 15 persistent classes and expire on fixed dates every 60 days at the end of the month, but are otherwise fully functional. *************** JVMS COMPATIBILITY ******************** VBSF requires a Java2 Runtime Environment. As of v3.0, the JDK 1.1.x is not supported. For best performance we recommend running VBSF with the VM included in the JDK 1.4.1 or JDK 1.3.1. Earlier Java2 versions may also be used with VBSF. However, the following JDK environments are not recommended: JDK 1.2.0; JDK 1.3.0; and JDK 1.4.0 A bug in the JDBC/ODBC bridge included in the JDK1.2.0 final release results in an 'Invalid ResulSet State'exception when a PreparedStatement is reused after its result set has been closed. If you will be using the bridge in this version you must disable statement caching to avoid this problem. Statement caching is disabled by setting the 'Maximum Active Statements' option in the Advanced tab of the DB Configuration form to -1. A bug in the JDBC/ODBC bridge included in the JDK 1.3.0 leads to memory leaks. If during the binding of parameters an ODBC-Error occurs the used buffer in odbc is lost, because pinned by JNI. This occurs when using long data values with SQL Server-odbc and MS Access. ******************************************************************** ************* CHANGES FROM v3.11 TO v3.12 ************************* Compatibility * VBSF 3.1x has been thoroughly tested and found compatible with the JDK 1.4.1 environment. Bug Fixes * The OCollection.contains() method was returning incorrect boolean values under certain circumstances. * The OQuery and Database listEnumeration() method was returning incorrect values on heterogenous collection when JDBC statement caching was enabled. * When reusing an OQuery with parenthesis for multiple 'gets' on a collection, each time the query is executed it adds another set of parenthesis to the SQL - eventually this can reach the limit for the database and produce errors. * Database.undoAllChanges() was not removing new objects from owned collections. * Unnecessary database SELECT calls to attempt to load the owner of an owned object when the owned object is deleted and the reference attribute pointing to the owner is of a base or interface type implemented by multiple classes. ******************************************************************** ************* CHANGES FROM v3.10 TO v3.11 ************************* Bug Fixes * Unnecessary database SELECT calls to attempt to load a referenced object when the foreign key value is NULL. * When using the ConcurrencyAware interface, VBSF allowed performing only 1 update to an object, and subsequent updates failed. * Adding an object to a referenced collection could result in the removal of that object from another referenced collection in an associated object. * When the OReference attribute was modified, a call to OReference.getValue() still returned the previous value. API New Features * The following method was added to the Server class: /** * Removes all Database objects assigned to the current thread, if any. * This method is useful if only one Database object must be assigned to the current thread, but * it's possible that other Database objects may have been assigned to the current thread in the past. * This could happen if an application server maintains a pool of reusable threads and your application * uses the Database.setThread() or Server.setDatabaseThread() to explicitly assign a Database to the * current thread. In that case, this method should be called prior to Database.setThread() or * Server.setDatabaseThread() to ensure that only the current Database is assigned to the current thread. * @return true if the current thread had previously assigned Database objects and they were succesfully removed. */ public final boolean removeAllDatabasesForThread(); ******************************************************************** ************* CHANGES FROM v3.03 TO v3.10 ************************* 1.1. New Features One of the most important new features in v3.10 is XML support. To utilize any of the XML features of the Mapping Tool and Persistence Layer you must update the CLASSPATH to include the sax.jar, jaxp-api.jar and xercesImpl.jar files from Sun's Java API for XML Processing (JAXP) package, which is freely available from Sun at: http://java.sun.com/xml/ If you will not be using any of the XML features, then the XML jar files listed above are not required to be present in the CLASSPATH. MAPPING TOOL New Features * Mapping schemas and configurations can now be saved in XML format. To save an existing schema to XML format, simply use the File->Save As menu option and enter the name of the schema with an extension of xml (e.g., contactdemo.xml). To save a configuration use the [Save as File] button and enter the name of configuration with an extension of xml. The mapping tool can still save to binary format, by either specifying the appropriate extension (.schema and .config) or by not specifying an extension. Schemas and configurations will save to the same format they were loaded in (XML or binary) when using the File->Save menu option. * The mapping tool will not allow adding schema objects with duplicate names (e.g., 2 classes with the same name in the same package). API New Features * Object graphs can now be converted to XML and XML documents converted to object graphs via the 2 new methods of the Database class listed below: /** * Returns an array of objects from the supplied XML Reader. In the case where the XML updates the * persistent state of one or more objects or specifies the creation of new objects, the objects returned * by this method may be used to perform the updates or inserts in the database directly. * @param reader reader containing XML document. This may be a FileReader if the XML coming from a file, * a StringReader if the XML coming from a String object, or an InputStreamReader if the XML coming from * a stream based device. When the Reader will perform I/O, it is advised that the reader * be wrapped in a BufferedReader to improve I/O performance. * @param xmlInfo information about how the XML document is to be parsed. * @return array of persistent objects, or null if none found. Only root objects are returned. Associated objects defined * with shallow retrieval are accessed via the standard collection and reference traversal operations. If all root * objects returned belong to the same class, the array returned is a castable array. * @exception BOXMLException if an error occurs during the XML conversion process. This exception wraps the underlying exception. */ public Object[] xmlToObjects( java.io.Reader reader, com.objectmatter.bsf.xml.XMLDocInfo xmlInfo ) throws BOXMLException; /** * Writes the XML representation of the supplied object array to the supplied Writer. * @return objs array of persistent objects from which to generate XML. * @param writer writer to which XML document will be written. This may be a FileWriter if the XML will be saved to a file, * StringWriter if the XML will be saved to a String object, or an OutputStreamWriter if the XML will be saved to * a stream based device. When the Writer will perform I/O, it is advised that the writer * be wrapped in a BufferedWriter to improve I/O performance. * @param xmlInfo information about how the XML document is to be generated. * @exception BODBException if the database operation cannot be performed, * or if the supplied command name has not been defined, or if the * supplied command name is of the wrong type. * @exception BOXMLException if an error occurs during the XML conversion process. This exception wraps the underlying exception. */ public void objectsToXML( Object[] objs, java.io.Writer writer, com.objectmatter.bsf.xml.XMLDocInfo xmlInfo ) throws BOXMLException; For examples of how to use the above 2 methods, refer to the ContactXMLApp client of the vcontactdemo sample application. * An owned object can now be moved to another owner by simply adding it to the owned collection of the new owner. Below is some sample source that shows how to move an owned object. The code is based on the vcontactdemo sample app, in which Contact owns Locator: //Moves Locator with No=332-1500 from Contact #7 to Contact #21 //Find Locator to move Contact currContact = (Contact) db.lookup( Contact.class, 7L ) ; Locator locToMove; Locator[] allLoc = (Locator[])currContact.getLocators() ; for ( int i = 0; i < allLoc.length; i++ ) { if ( allLoc[i].getLocatorNo().equals("332-1500") ) { locToMove = allLoc[i]; break; } } //move the Locator to Contact #21 Contact newCt = (Contact) db.lookup( Contact.class, 21L ) ; newCt.addLocator(loc); //the add operation to the new owner automatically performs the move //both the old and new owners must be updated in the context of the same transaction to ensure all shared caches are updated db.startTrans(); db.update(newCt) ; //updates owned Locator in db db.update(currContact) ; db.commit(); * The following method has been added to the Database class: /** * Returns the current list of registered AttributeChangedListeners, or null if none */ public AttributeChangedListener[] getAttributeChangeListeners() { 1.2. Bug Fixes * A query or lookup operation, followed by full loading of the object cache, for a particular class, could cause a global cache inconsistency. * A collection's isEmpty() method could return false while size() returned a number greater than zero. The isEmpty() and size() methods now return matching results. * Incorrect objects could be returned when traversing a reference if new objects of the referenced class existed in the cache. In that case, a new object could be returned instead of the actual referenced object. * BOValidityCheckException reason codes were not public. They are now listed in the BOValidityCheckException class. * The Database.unDelete() method was not working properly under Optimistic Transaction Management mode. * When defining a Filter Column based on nullability using the mapping tool, the data type was modified after a subsequent retrieval. * The mapping tool did not allow entering a referenced attribute name when the referenced class was an interface. ******************************************************************** ************* CHANGES FROM v3.02 TO v3.03 ************************* 1.1. New Features MAPPING TOOL New Features * New source code template tags: PREFIX_OUTPUT_SPEC SUFFIX_OUTPUT_SPEC Allow specifying an alternate output package name and/or class name for source code generation. This is useful, for example, for generating interfaces or entity beans for the persistent classes. The tags accepts 2 arguments. The first argument is the alternate package name. The second argument is either a prefix or suffix used to concatenate to the persistent class name in order to come up with the alternate name. At least one of the arguments must be specified. Below are some examples of usage, based on a persistent class named com.persistent.Customer: %SUFFIX_OUTPUT_SPEC com.interface Intf% - generates an interface named com.interface.CustomerIntf %PREFIX_OUTPUT_SPEC com.interface Intf% - generates an interface named com.interface.IntfCustomer %SUFFIX_OUTPUT_SPEC Intf% - generates an interface named com.persistent.CustomerIntf %SUFFIX_OUTPUT_SPEC com.interface % - generates an interface named com.interface.Customer (note the space after the package name inside the tag) Note that these tags are used only for the names of the directories and files created during generation. The template itself must also use the correct prefix/suffix in the class name and the alternate package name. When used either tag must be placed on top of the template file, before all other tags (except for the COMMENT tag, which may be placed before). For an example, please see the new template6.tmpl template in the schrepository directory. * Enhanced command line source code and DDL template generation: (a) Ability to specify multiple template names in the map tool command line for generating source code or DDL scripts. This is done by specifying multiple comma-separated templates in the -t option. All classes in the schema will be generated against each template. For DDL this is useful to generate multiple DDL scripts, each against a different template, such as createtablesddl.tmpl, droptablesddl.tmpl, and grantddl.tmpl. For source code generation, this option must be used in conjunction with the new PREFIX_OUTPUT_SPEC and SUFFIX_OUTPUT_SPEC tags to allow generating multiple source files (e.g., a class and an interface) for each persistent class. (b) Ability to specify a specific Java package within the schema for which to generate. This allows generating sources and/or DDL for each Java package against different templates. For examples of both, please see the 'Running the Mapping Tool' section in the Installation Instructions. * Package and Class names now appear in alphabetical order in the mapping tool tree. New packages and classes always appear last on the list on the same session that they were created. However, the next time the schema is reloaded from disk, the new packages and classes will be sorted. * Ability to specify whether the cache will be local (i.e. in each Database) or global (i.e. shared by all Databases) on a per class basis. This is done in the Cache Configuration section of the Class Mapping form. This setting applies only to the Enterprise Edition, as the Professional only supports a local cache. API New Features * New Server methods: /** * Returns all Database objects assigned to the current thread, or null if no Database * objects have been assigend to the current thread. This method is useful to determine if * multiple Database objects have been assigned to the current thread, and if so, which ones. */ public final Database[] getAllDatabasesForThread(); /** * Return true if there is a Database object assigned to the current Thread. */ public final boolean containsDatabaseForThread(); /** * Return true if there is a Database object assigned to the supplied Thread. */ public final boolean containsDatabaseForThread(Thread thread); * New Attribute Change Event Mechanism to track attribute changes in persistent objects. For details see the API on: com.objectmatter.bsf.event.AttributeChangedEvent, com.objectmatter.bsf.eventAttributeChangedListener com.objectmatter.bsf.Database: addAttributeChangedListener, removeAttributeChangedListener 1.2. Bug Fixes * java.lang.IndexOutOfBoundsException during heterogeneous collection retrievals and on explicit discard operations. * StackOverFlow due to a circular owned relation when the reference to the owner class was of the referenced type. * Optimistic Transactions now have a corresponding db transaction in progress too: a) Rollback was not rolling back the corresponding db txn. b) Could not execute update stored procedures in the context of the optimistic transaction * In optimistic txn, any database updates performed in the preUpdate and posUpdate methods in objects that implement OPersistable did not result in actual db operations. * OCollection.removeAll(Collection c) was throwing an "OperationNotSupported" exception. * Composite ID objects that used references of an interface type as part of the ID resulted in BOMappingException with Invalid number of ID attributes message. * Persistence by reachability was not working properly if one or more objects in an ownership line were not modified in the current transaction. * "BOCacheUpdateConflictException: Transactional cache invalid. A removed element was already removed in the global shared cache. Holder must be refreshed from global cache." was thrown at commit/update time of an owner object when a new owned element was added to its owned collection and subsequently removed prior to committing the transaction or performing the update. * When exporting a schema to text in the maptool, filter column and table names were reversed for SUPERSET classes with a filter column defined. * Queries that go the database did not add any objects present in the transactional cache (i.e. new objects) that match the query spec to the result set. This appears to be the case only when using a query and the cache is not loaded in full. * Queries that went to the database were not adding any objects present in the transactional cache (such as new objects) that matched the query spec to the result set. This occurred only when using a query and the cache was not loaded in full. * A query that has no search parameters and whose maximum count has not been specified now sets the cache as loaded in full. Examples of such queries are empty queries with only a DISTINCT or ORDER clause. ******************************************************************** ************* CHANGES FROM v3.01 TO v3.02 ************************* 1.1. New Features * Reflection Attribute and Method access speed improved. * Performance improvements in heterogeneous collections. * Option to disable enforcement of use of internal versioning mechanism for concurrency control via the new Server.setEnforceVersionControl() method. See the API Reference for details. * The following Server constructors and factories have been added to allow for easier schema manipulation at application startup: public Server(AppSchema schema); public Server(AppSchema schema, DBConfiguration dbConfig); public Server(AppSchema schema, int initNoDatabases); public Server(AppSchema schema, int initNoDatabases, int maxNoDatabases, long dbPoolTimeout, int timeoutThreshold); public Server(AppSchema schema, int initNoDatabases, int maxNoDatabases, long dbPoolTimeout, int timeoutThreshold, DBConfiguration dbConfig); public static Server createServer(String name, AppSchema schema, int initNoDatabases, int maxNoDatabases, long dbPoolTimeout, int timeoutThreshold, DBConfiguration dbConfig); public static Server createServer(String name, AppSchema schema, int initNoDatabases, int maxNoDatabases, long dbPoolTimeout, int timeoutThreshold); public static Server createServer(String name, AppSchema schema, int initNoDatabases, int maxNoDatabases); public static Server createServer(String name, AppSchema schema, int initNoDatabases, int maxNoDatabases, DBConfiguration dbConfig); 1.2. Bug Fixes * Database.update() not working when a clone of the object retrieved was passed to the update method, resulting instead in a transaction rollback. * NullPointerException in Database.update() due to invalid REMOVED FROM CACHE objects in the cache. * Database and OCollection size() methods that did a SELECT COUNT were not adjusting for added & removed objects. * Removal of objects from a collection would result in the object added back. * Database and OCollection size() calls causing "BOMappingException: Invalid attribute name null" when used on a composite ID class and the cache not loaded in full from the database. * NullPointerException in SchemaManager.setSchema(AppSchema). * NullPointerException wrapped inside a BOMappingException when adding a new composite ID object to a collection containing a reference attribute to its owner, for which a value was not assigned. * An object removed from a many-to-many referenced collection would show up on the collection of another instance (i.e. a clone) of the same holder object. ******************************************************************** ************* CHANGES FROM v3.00 TO v3.01 ************************* 1.1. New Features * JDO API support. This release provides implementation of the JDO PersistenceManagerFactory, PersistenceManager, Extent and Transaction interfaces. Missing is support for the JDO Query language, which is planned for implementation by v3.1. See the JDO Support section in the Installation Instructions for details. * Persistent objects with java.util.Collection and referenced interfaces can now be instantiated directly via the Java new operator. There is no need to use the Database.create() method. The vposdemo sample application demonstrates this feature. * New Optimistic Transaction Management Mode that allows multiple calls to Database.update() for the same object in the same transaction. For details please see API docs for the Database.setOptimistic(boolean) method. * Ability to specify case sensitivity in LIKE queries via the new BOP_Query.VBSFsetLIKECaseSensitivity(boolean). * The following methods are now available in the Database class. For details see the API Reference. //returns a single object with the specified object id from the object cache. public Object lookup(Class persistentClass, Object id); //assigns this Database object to the current thread. public void setThread(); * The following method is now available in the Server class. For details see the API Reference. //assigns a Database object to the current thread. public void setDatabaseThread(Database db); 1.2. Bug Fixes * Removed the following SUPERSET mapping restriction when defining joins: "The ID column name of any table *after* the second table in the inheritance tree must be named the same as the ID column name of the second table" The column names may now be named differently. However, when defining joins, tables must be joined in the same manner as their inheritance relationship. For example, in the vpersondemo sample app there is the following inheritance relationship: Person <|-- Customer <|-- CorpCustomer Person is abstract; Customer is a concrete subclass of Person, and CorpCustomer is a subclass of Customer. In the SUPERSET CorpCustomer class the following joins are defined now: Person.ID=Customer.CustomerID Customer.CustomerID=CorpCustomer.CorpCustomerID In the previous version of the sample, the joins of both children tables were pointing to the same parent table, as shown below: Person.ID=Customer.CustomerID Person.ID=CorpCustomer.CorpCustomerID <=== INCORRECT JOIN The second join is incorrect because the CorpCustomer table should join with the Customer table, instead of with the Person table. While the sample will still run with above joins, this way of defining joins (where all children tables pointing directly to the same parent table) is no longer recommended as it is prone to SQL ordering problems. * The Database.refresh(String) and Database.refresh(object) methods were not working properly. * A "Missing java type for attribute XXX" error when generating source code in the mapping tool when the Java data type is left blank. * A BOInvalidClassException was thrown when trying to do a Database.lookup(Class,id) and the class supplied was an abstract class that only had one concrete subclass. * A Server.shutdown() was not automatically removing the Server object from the internal named Servers table, causing a problem with a subsequent creation of another Server with the same name. * The DDL generation feature in the Mapping Tool was ignoring join tables defined in abstract classes. * When traversing a reference that was defined to refer to any object that implements a specific interface, any objects of classes that implemented subinterfaces of the referenced interface were ignored. * A java.lang.ClassCastException was thrown when inserting an object with other owned objects when using explicit transaction control. * It was not possible to delete referenced objects inside the preUpdate() method of classes that implement the OPersistable interface. * Calling a size() or sizeForClass() method on a class or collection, whose extent was not cached was resulting in an incorrect SELECT COUNT query, which could return a different result when the collection is cached. This was due to the SELECT COUNT missing the DISTINCT keyword. * If VBSF tried to rollback the transaction, but the rollback failed at the database level, VBSF did not end the transaction. As a result, the transaction was still pending in VBSF. Now VBSF internally end the transaction regardless of whether the rollback fails. ******************************************************************** ************* CHANGES FROM v3.0 rc2 TO v3.00 ********************** 1.1. New Features * Support for contained objects mapped to a subset of a table in the class via the new attribute type CONTAINED OBJECT (Important note: The old CONTAINED OBJECT attribute type that mapped to a binary column has been renamed to CONTAINED BLOB OBJECT). This is demonstrated in employeedemo (SUBSET Employee.myPhone) & contactdemo3 (SUPERSET InternationalPhone.country) sample apps. * Server.checkAllPooledConnections() and Server.checkPooledConnections() are now blocking methods that do not require a Thread.sleep() to allow for completion. 1.2. Bug Fixes * Incorrect SQL generated when performing an AggregateOQuery in a many-to-many heterogeneous collection. * Objects with external IDs added to a collection were being returned twice. * Database.refresh(String className) was not properly refreshing the objects. * The mapping tool DDL generator was incorrectly computing the number of columns in the case of composite column REFERENCE attributes. * Incorrect object was being looked up from the cache after a refresh operation. * "BOReferenceNotUpdatedException: Database.setReference(): Referenced object not found. Make sure its object ID has been assigned." thrown when an object that was just inserted in the db was being assigned to a reference in the course of the same transaction. * A collection get() operation returned null after a transaction commit. 1.3. Known Oustanding Issues * A BOUpdateConflictException can be thrown when directly deleting owned or referenced objects via a Database.delete(obj) operation, and subsequently deleting the owner or performing a removeAll() on the collection. To avoid this problem make sure that owned objects are deleted by removing them from its owned collection and updating the owner, or that all direct Database.delete(obj) operations are preceded by an explicit removal from the collection(s) the owned or referenced objects belong to. * Database discard operations do not work properly on owned classes. As a result discard should only be used on root objects. Discarding an owner object will in turn automatically discard all its owned objects. 1.4 Documentation * The employeedemo and contactdemo3 sample applications have been updated to demonstrate the use of contained objects. * All documentation and sample applications have been updated for v3.0. ******************************************************************** ************* CHANGES FROM v3.0 rc1 TO v3.0 rc2 ******************** 1.1. Major API Changes For details on all the API changes below consult the API Reference. * The OCollection class now implements java.util.Collection so REFERENCED COLLECTION attributes with a Java data type of OCollection do not have to be declared as OCollection in the persistent class and instead can be declared as the standard Java interface java.util.Collection. This allows your persistent classes to be fully decoupled from VBSF while still taking advantage of the lazy retrieval capabilities of the OCollection class. See the vposdemo sample application for an example. * Support for allowing the Java data type of a REFERENCE attribute to be declared as an application specific interface. This allows your persistent classes to be fully decoupled from VBSF while still taking advantage of the lazy retrieval capabilities of the OReference class. Support for this new feature requires a 1.3.x JVM. See the vposdemo sample application for an example. * New AggregateOQuery class used to execute SQL aggregate queries such as COUNT(*), COUNT(col), MAX(col), etc. directly against the RDBMS. See the vcontactdemo2 sample application for some examples. * All Datababase.size() and OCollection.size() methods have been updated to perform a SELECT COUNT(*) query if the collection is not already loaded in the cache. Previous behavior was to load the collection. * The Database pool now uses WeakReferences so if an application thread ends without closing its associated Database object, the Database object will be automatically closed and released to the pool by VBSF. * New Database.discardAll(boolean global) and Database.discardAll(String className, boolean global) methods that allow discarding the transactional, and optionally the global, caches on demand. * All Database.open() methods have been deprecated. To specify the login information at runtime pass a DB Configuration object to the Server constructor to get pre-opened Database objects from the Server. In this case, it is not necessary to define the DB Configuration at design time using the mapping tool and as a result, the 'Client logins' and 'Client can supply connection' options in the DBConfiguration options have also been deprecated. * Validity checks for attributes of type REFERENCE are now supported. 1.2. Major Mapping Tool Changes * Added the following source code generation tags to support REFERENCED COLLECTION attributes of Java type Collection (java.util.Collection): JAVACOLLECTION, OWNED_JAVACOLLECTION, REFERENCED_JAVACOLLECTION * Added the following source code generation tags to support REFERENCE attributes of Java type where an interface is specified: OWNED_REFERENCED_INTERFACE, REFERENCED_REFERENCED_INTERFACE, CONTAINED_REFERENCED_INTERFACE, REFERENCED_INTERFACE A new template5.tmpl template has been added to the schrepository directory included in the docs that demonstrates the use of these new tags. See the README.TXT file in the same directory for details on this new template. 1.3. Bug Fixes * BOUpdateConflictException: Update conflict detected in XXX. Data modified by another user. * Exception that occurred on objects with SUPERSET mapping for which a SQL Statement was defined instead of joins. * NullPointerException when executing a query from the cache where some of the query attributes were indexed. * VBSF was changing to lowercase the path of schema files, causing problems in Unix based machines. * Database.addToCollection() bug that caused extra SELECTs when using using addToCollection() in the middle of a transaction with objects with external IDs. * NullPointerException when retrieving objects with REFERENCES with deep retrieval. 1.4 Documentation * The vposdemo sample application has been updated to demonstrate the use of OCollection declared as java.util.Collection and REFERENCE attributes declared as an application specific interface. * The vcontactdemo2 sample application has been updated to demonstrate the use of the AggregateOQuery class. The installation instructions, API Reference and all sample applications have been updated for v3.0. The Mapping Tool Guide and Programmer's Guide have not. However, all major changes from v2.41 to v3.0 are documented in this file. ******************************************************************** ************* CHANGES FROM v2.41 TO v3.0 rc1 ************************ 1.1. Major API Changes For details on all the API changes below consult the API Reference. * Exception BOUpdateConflictException is now thrown from all OCollection add/remove and all OReference.set methods. * A Server object is required. Database cannot be directly instantiated anymore and its open() method cannot be called unless passing it login parameters. * Runtime schema modifications are now done via Server.getSchemaManager(). Schema modifications methods are not available in Database class anymore. * New Database.closeConnection() and isConnectionClosed() methods to be used to close the connection without closing the Database itself. * Use of Database.create() is not required only because a class has OColllection or OReference attributes. The object constructor can now directly initialize the OColllection and OReference attributes in the object. As a result the new operator may now be used to instantiate objects with OColllection and OReference attributes. * New Database.initRelationships() method that initializes OCollection and OReference attributes of objects that were created via the new operator. * Database.attach() removed. Objects with OColllection and OReference attributes can be freely used with different Database objects within the same thread with the caveat that additions and removals to a collection are kept in a Database transactional cache, therefore such changes must be saved to the database before closing the current thread's Database object. * Contained references are not updated via the markUpdate() method. Instead the OReference.set() or Database.setReference() must be used. * When VBSF is used with a middleware product that manages transactions the Database.commitMemory() method should be called to record the successful completion of the database transaction in the VBSF global shared cache. In addition, the 'Disable automatic transactions' option should be checked to prevent VBSF from starting its own db transactions. If a VBSF connection pool is used, then the Database.startMemoryTrans() method must also be used, as shown in the example below: db.startMemoryTrans(); db.update(currContact); db.commitMemory(); * Owned objects should now be deleted via the OCollection.remove() or Database.removeFromCollection() methods instead of the Database.markDelete() method as this method does not update the status of the collection in memory. * Database.refreshLocal() is removed. Use Database.refreshFromCache() instead which refreshes the values of the supplied argument. All other Database.refreshXXX() methods now return a boolean. * The object status constants returned by the Database.getStatus() method have been moved from the BOP_persistent class to the PersistentStatus interface. A new Database.getCurrentStatus() method has been added that automatically introspects the object passed as argument. * New Database.list(Object idObject) that returns an object matching the ID of the supplied idObject directly from the database. 1.2. Major Mapping Tool Changes * The TABLE class mapping has been removed, old schemas with TABLE mappings are automatically converted to SUBSET. * The Class Mapping Form now includes a 'Cache Configuration' section for defining cache parameters on a per class basis. VBSF supports 3 types of caches: Static, Soft and Weak. Static caches are never garbage collected. Soft and Weak caches are garbage collected according to the JVM policies for Soft and Weak references. Caches can be defined as 'Managed', in which case VBSF manages the cache using an MRU algorithm. For details on cache configuration options see the API Reference of the com.objectmatter.bsf.mapping.schema.CachePolicy class. * The DB Configuration 'Automatic discard of cache' option applies only to the transactional cache in the Enterprise version. The Global shared cache is not affected. In general this option is not recommended in the Enterprise version. * The 'Automatic memory commit' option has been removed from the DB Configuration options. * The 'Full discard mode' option has been removed from the DB Configuration and Database API as it is no longer necessary. * The JDBC driver may now be left blank in the mapping tool allowing dynamic assignment of a JDBC driver at runtime via the Database.loadDriver() method. 1.3. Bug Fixes * The 'Leave auto-commit enabled' in DB Configuration was ignored. * The Database.close() can now be called from a thread different than the one that originally allocated it. * Validity checks for references are now supported. 1.4 Documentation The installation instructions, API Reference and all sample applications have been updated for v3.0. The Mapping Tool Guide and Programmer's Guide have not. However, all major changes from v2.41 to v3.0 are documented in this file.