@version $Id$
========================================================================
ObJectRelationalBridge -- Bridging Java Objects and Relational Databases
========================================================================

ObJectRelationalBridge (OJB) is an Object/Relational mapping tool that
provides transparent transactional persistence for Java Objects against
relational databases. OJB provides ODMG and JDO interfaces.

---------------------------------------------------------------------
Release 1.1_alpha
---------------------------------------------------------------------
NEW FEATURES:
- OJB can now use constructors and factory methods withg arguments. The new
  creation-descriptor element is used to define the used constructor/factory method.
- It is now possible to use database procedures for retrieving objects by their identity
  (primary key values) and by their foreign key values (for elements of a collection).
  Two procedure descriptors have been introduced to this end: select-by-pk-procedure
  and select-by-fk-procedure. Also, corresponding XDoclet tags are also available.
- When querying for Proxies the select statement contains the pk-columns only. 
  This feature may help to solve memory problems. 
- Proxy generation is now pluggable with two implementations (standard Java proxies,
  CGLib proxies)
- Better support for attributes containing expressions ie. sum(0.9 * price * stock). 
  Restriction: All attributes contained in the expressions have to belong to the same table ! 
- ManageableCollection interface has been extended: all ojb... Methods now also receive a
  PersistenceBroker instance
- Forward-port from 1.0 stable:
  New ant-target ojb-quickstart creates archives of ready-to-run apps for tutorials 1 and 2
  complete with pre-created Hsqldb databases (based on ojb-blank).
  These archives are also available in the binary download area.
- Relationships based on non primarykey fields. These fields are defined in the new 
  attribute "target-field-ref" of inverse-foreignkey and foreignkey in collection- and
  referenceDescriptor. If the target-field-ref is missing the primary key of the referenced
  class is used.
  
     <class-descriptor
         class="org.apache.ojb.broker.NoPkReferenceTest$Article_2"
         table="Artikel_2" >
      <field-descriptor
         name="articleId"
         column="Artikel_Nr"
         jdbc-type="INTEGER"
         primarykey="true"
         autoincrement="true"
      />
	  ...
      <field-descriptor
         name="productGroupName"
         column="KatName"
         jdbc-type="VARCHAR"
      />
	  ...
      <reference-descriptor
            name="productGroup"
            class-ref="org.apache.ojb.broker.NoPkReferenceTest$ProductGroup_2"
      >
         <foreignkey field-ref="productGroupName" target-field-ref="groupName"/>
      </reference-descriptor>
   </class-descriptor>

   <class-descriptor
         class="org.apache.ojb.broker.NoPkReferenceTest$ProductGroup_2"
         table="Kategorien_2" >
      <field-descriptor
         name="groupId"
         column="Kategorie_Nr"
         jdbc-type="INTEGER"
         primarykey="true"
         autoincrement="true"
      />
      <field-descriptor
         name="groupName"
         column="Kategorie_Name"
         jdbc-type="VARCHAR"
      />
      <field-descriptor
         name="description"
         column="Beschreibung"
         jdbc-type="VARCHAR"
      />
      <collection-descriptor
         name="allArticlesInGroup"
		 element-class-ref="org.apache.ojb.broker.NoPkReferenceTest$Article_2"
         auto-retrieve="true"
         auto-update="true"
         auto-delete="false"
      >
         <inverse-foreignkey field-ref="productGroupName" target-field-ref="groupName"/>
      </collection-descriptor>
   </class-descriptor>
- The creation of collection objects for collections or queries is now handled via a pluggable
  collection factory. The setting CollectionFactoryClass in OJB.properties specifies the
  concrete implementation to use which must implement org.apache.ojb.broker.accesslayer.CollectionFactory.


NOTES:
--

CHANGES:
- OJB no longer generates OUTER joins when both ends of a relationship point to the same class.
  Use setPathOuterJoin("path") to force an OUTER join.
  
- replaced ojbConcreteClass by a discriminator-descriptor:

 <class-descriptor
       class="org.apache.ojb.broker.MultipleTableExtentAwareQueryTest?$ExtentA?"
       table="EXTENT_TEST_A"
 >
       <discriminator-descriptor
         column="class_name"
         jdbc-type="VARCHAR"
         value="MTEA_Ext_A"
      /> 

     <field-descriptor
        name="objId"
        column="OBJ_ID"
        jdbc-type="INTEGER"
        primarykey="true"
        autoincrement="true"
     />
 </class-descriptor>

 the discriminator is compatible with the old ojbConcreteClass. If the optional attribute
 'value' is not defined, the name of the class from class-descriptor is used.
- delete uses the discriminator column in the where-clause (if it's not already part of the pk)
  DELETE FROM MYTAB WHERE id = 1 and class_name = 'my_class_a' 
- QueryByExample: New class QueryByExample; the constructor QueryByCriteria(Object anExample) has been removed !  
  The handling of primitives has been improved a little. It's possible to ignore primitive 0 by using 
  QueryByExample#setIgnoreZero(true).
- Added support for new IdentityCriterion : 

        Person p = new Person();
        p.setId(1);
        p.setFirstname("tom");
        Identity id = broker.serviceIdentity().buildIdentity(p);

        Criteria crit = new Criteria();
        crit.addIdentityEqualTo("persons", id);

        Query q = QueryFactory.newQuery(Project.class, crit);
        Collection results = broker.getCollectionByQuery(q);

- refactored ojb.broker.util.collections
  RemovalAwareCollection is no longer a subclass of Vector, for backward compatibility it's
  still a List. RemovalAwareCollection will be replaced by ManageableTackingListImpl.
  The interface IRemovalAwareCollection no longer exists. 
  The behaviour of the RemovalAwareCollection has been changed: the new implementation checks if the 
  object could be removed from the collection before registering it as deleted. The old implementation registered
  any object as deleted whether it existed in the collection or not.
- moved handling of TrackingCollection (former IRemovalAwareCollection) to PersistenceBrokerImpl.
- new support for quoting table and column names 
  the ojb quoting character is '. this character is replaced with the platform
  specific character when generating the sql. 
  'myTable' will be converted to "myTable", [myTable] etc. depending on Platform#getQuotedName
- replace PersistentField implementations
- updated hsqldb to 1.7.3
- updated torque to 3.1.1
- updated commons-collections to 3.1
- updated commons-pool to 1.2

BUG FIXES:

- fixed OJB297
- fixed OJB296
- fixed issue with CollectionProxy and RemovalAwareCollection
- RemovalAwareCollection is no longer the default collection-class for m:n-relationships
- ManageableCollection#afterStore is only called if cascadeStoring is CASCADE_OBJECT

- mixing of mappings 1-table/1-class and 1-table/many classes is now supported
- ojb no longer adds groupBy columns to the SELECT-clause, orderBy columns are still added because of sapdb
- orderBy columns of the original query are used as joinAttributes in count-query
- ALIAS-prefix again works for report-queries (see QueryTest#testReportQueryAlias) 

KNOWN ISSUES:
- Subqueries are not extent aware. see QueryTest#testSubQueryAgainstExtents


More information is available at http://db.apache.org/ojb

 Copyright � 2002-2004  The Apache Software Foundation. All rights reserved.