<% header(name + ' 0.9 Release Notes') %>

<p><% name %> version 0.9 released on 11/13/05</p>

<a id="Incompatible"></a><h2>Incompatible Changes</h2>

<p><span class="warning">There are some MiddleKit improvements that break
compatibility with previous versions of MiddleKit, although all are easy
to address.</span> In a nutshell, if you are upgrading MiddleKit <em>for
an existing project</em>, take the following steps:</p>

<ul>
  <li>Add these to Settings.config inside the model:
<pre class="py">{
    'SQLSerialColumnName': '%(className)sId',
    'UseBigIntObjRefColumns': True,
    'AllowRefreshOfChangedObjects': True,
}</pre></li>
  <li>If your model has a SQLGenerator.config file, move its contents to
  Settings.config.</li>
  <li>If you use Microsoft SQL Server and your model uses the float type
  then read the section below detailing that.</li>
</ul>

<p>Below are more details about the incompatible changes.
Below that are more general notes on this release.</p>

<h3>Obj Ref Columns</h3>

<p>A long standing flaw in MiddleKit was the use of 64-bit integer SQL
columns to store references/pointers to objects. The first 32-bits were
for the class id and the second 32-bits were for the object id,
information that is necessary because of inheritance and the creation
of one SQL table per Python class. These 64-bit columns, packed with
two numbers, are difficult to work with from SQL. For example, an object
reference to (classId=1, objId=1) showed as 4294967297 in SQL and could
not be readily joined with other tables.</p>

<p>The new approach is to break these values into two SQL columns.
If the attribute name is "foo" then the SQL columns will be named
"fooClassId" and "fooObjId". If, for some reason, you don't like
those suffixes, you can customize them through the setting
<a href="UsersGuide.html#Configuration_ObjRefSuffixes">ObjRefSuffixes</a>.
As always, the class ids are stored in the _MKClassIds table that
MiddleKit automatically generates.</p>

<p>Another useful benefit is that the fooClassId columns are now given
default values to match the class id of the target class (in other words,
the integer id of class Foo). When the target class has no subclasses then
the fooClassId column can be safely ignored in INSERTs, UPDATEs and SELECTs.
The point of this is to make the database even easier to work with from SQL.</p>

<p><span class="warning">If you are upgrading Webware then your database
schema will no longer be compatible with MiddleKit.</span> The easy way
to fix this is to set UseBigIntObjRefColumns to True in Settings.config (see
<a href="UsersGuide.html#Configuration_UseBigIntObjRefColumns">User's Guide
- Configuration</a> for more information). This will give you the old behavior.
The hard way is to fix up your schema and migrate the data from the old
columns to the new.</p>

<h3>Serial Number Column</h3>

<p>MiddleKit creates a SQL table for every concrete class, and each table
has a column for the serial number of a record. This column is the primary key
for the table. Its new default name is <span class="name">serialNum</span>
which matches the MiddleObject method of the same name and fits MiddleKit
naming conventions. You can control this with a
<a href="UsersGuide.html#Configuration_SQLSerialColumnName">new setting</a>.</p>

<h3>SQLGenerator.config</h3>

<p>There used to be another config file, besides Settings.config, named
SQLGenerator.config, with a single setting, DropStatements. That file is
no longer used and the setting has been moved to Settings.config.
If you have SQLGenerator.config in a model directory, move the setting over.</p>

<h3>MS SQL Support</h3>

<p>The <span class="name">float</span> type now yields a SQL type of
<span class="name">float</span> rather than <span class="name">decimal</span>,
because that matches the semantics of Python's float type more closely
(perhaps identically). If you want decimal, use decimal; it is a valid
MiddleKit datatype.</p>

<p>The serial primary key field is now typed as int instead of bigint.
This matches the MiddleKit approach for other databases and also allows
object id columns to be foreign keys to this primary key (MS SQL will give
an error if an int column tries to reference a bigint column).</p>

<h3>Protection against losing changes</h3>

<p>Depending on the application, certain call sequences can cause
uncommitted changes to be lost.  This might be due to programmer error
(i.e. forgetting to call saveChanges when necessary), but can also happen
due to the implementation of store.deleteObject(), which executes SQL queries
(and refreshes objects) when locating and resolving object references
(i.e. cascade, detach).</p>

<p>In order to protect the programmer against such errors, which may be
very subtle and difficult to detect, MiddleKit will raise an assertion
error when a changed object's attributes are about to be refreshed from
the database.  The programmer should then add calls to store.saveChanges()
to ensure that data loss cannot occur.</p>

<p>Since this change may break existing applications, a new setting
called "AllowRefreshOfChangedObject" has been added. This setting defaults
to false (strongly recommended), but for existing applications you may
set it to true to avoid ever getting an assertion failure.</p>

<a id="NewFeatures"></a><h2>New Features</h2>

<ul>
  <li>MiddleKit now includes full support for PostgreSQL
  (<a href="UsersGuide.html#RDBMS">docs</a>).</li>
  <li>You can specify a <b>SQLDefault</b> for attributes
  (<a href="UsersGuide.html#MT_SQLDefault">docs</a>).</li>
  <li>For list references, you can specify the name of the "back reference"
  attribute explicitly.  This allows creation of recursive structures,
  such as trees (<a href="UsersGuide.html#DT_Recursive">docs</a>).</li>
  <li>A setting called "DatabaseArgs" was added in which you can pass
  necessary arguments for establishing the database connection
  (<a href="UsersGuide.html#Configuration_DatabaseArgs">docs</a>).</li>
  <li>You can clone Middle objects (recursively, if you want)
  (<a href="UsersGuide.html#MT_Cloning">docs</a>).</li>
  <li>In sample data files, you can put a comment after an obj ref value
  to remind you of what it points to; you do so in the same cell.
  For example, instead of just "User.17", you can say "User.17 - John Smith".
  One space is required after the number and the rest is ignored.</li>
  <li>A new setting, <b>GenerateSQLReferencesForObjRefsToSingleClasses</b>,
  causes MiddleKit to generate "references <i>TargetTable</i>(SerialNum)"
  in Create.sql for each obj ref column whose target class has no subclasses.
  This helps preserve data integrity at the database level.
  Caveat: Circular references don't work.</li>
  <li><p>MiddleKit will now generate CREATE TABLE statements in order
  of dependency (least to most) so that foreign key declarations always work.
  This relieves you of having to get the order of your classes "just right"
  in the model &ndash; in other words, you can have "forward references"
  &ndash; and presents another advantage over straight SQL.</p>
  <p>And MiddleKit does the same for your sample data as well.</p>
  <p>This change is unlikely to interfere with any existing projects,
  but just in case, you can turn it off with the
  <b>DoNotSortSQLCreateStatementsByDependency</b> setting
  (set it to True).</p></li>
  <li>A new setting, <b>AccessorStyle</b>, can be set to <b>'properties'</b>
  in which case MiddleKit will generate Python properties for attributes
  instead of the traditional methods foo() and setFoo()
  (<a href="UsersGuide.html#Configuration_AccessorStyle">docs</a>).</li>
</ul>

<a id="Improvements"></a><h2>Improvements and Refinements</h2>
<ul>
  <li><b>Generate.py</b> does a better job of detecting errors in the class
  definitions and sample values than before. You are more likely to see
  a useful error message than a cryptic traceback. However, in those cases
  where an exception does occur, you can see that just before the exception,
  Generate.py prints the last attribute that it was processing before the error.
  You can then search for that attribute in your model and troubleshoot it.</li>
  <li><b>Dump.py</b> is documented.</li>
  <li>When you delete an object, it is automatically removed from any list
  attributes in other objects.</li>
  <li>There is a new setting called '<b>CacheObjectsForever</b>', which
  defaults to False.  If set to True, the object store will cache objects
  indefinitely, which, depending on the size of your database, can use
  a lot of memory (this is the behaviour of previous versions of MiddleKit).
  If set to False, the object store uses "weak references" to cache the objects,
  which allows the Python garbage collector to collect an object as long
  as there are no other reachable references to that object. This change
  is unlikely to interfere with existing applications, but you can always
  set 'CacheObjectsForever' to True to get the old behaviour if you want.</li>
  <li>MiddleKit previously supporting using strings or mx.DateTime-et-al
  for any attributes typed date, time or datetime. String support has been
  dropped and support for Python's own datetime module has been added.
  You can still use mx.</li>
  <li>A new setting, <b>UseHashForClassIds</b>, can be set to true to
  cause internal class ids to be hashed from the class name, instead
  of numbered serially (1, 2, 3, ...)
  (<a href="UsersGuide.html#Configuration_UseHashForClassIds">docs</a>).</li>
  <li>There are good instructions on how to run the test suite in
  <span class="filename">MiddleKit/Tests/README</span>.</li>
  <li>MiddleObject.isDeleted() returns true for objects that have been marked
  for deletion. You cannot refresh such an object from the database.</li>
  <li>MiddleKit is now compatible with the new Decimal type in Python 2.4
  which can be returned, for example, by MySQLdb. By "compatible",
  I mean that the MK test suit passes. MK does not yet go out of its way
  to create Decimals.</li>
</ul>

<a id="Bugfixes"></a><h2>Bugfixes</h2>

<ul>
  <li>The default for the <b>UsePickledClassesCache</b> setting is now false.
  It occasionally created problems for multiple developers.</li>
  <li>MiddleKit no longer erroneously complains about certain deletion
  situations. Specifically, objects that still point to a deleted object
  should not cause an error if those objects are going to be deleted as well
  (via cascading deletes).</li>
</ul>

<% footer() %>
