Bug 114025

We should document frequent (or even not so frequent) PDL refactorings
in a tutorial format.  Most recent case in point is change 39552, in
which I went from this logical model:

  Model 1:
    association {
        Category[0..n] rootCategory = join acs_objects.object_id
                                        to cat_root_cat_object_map.object_id,
                                      join cat_root_cat_object_map.category_id
                                        to cat_categories.category_id;
        ACSObject[0..n] categoryOwner = join cat_categories.category_id
                                          to cat_root_cat_object_map.category_id,
                                        join cat_root_cat_object_map.object_id
                                          to acs_objects.object_id;

        String[0..1] useContext = cat_root_cat_object_map.use_context;
    }

to this model

  Model 2a:
    object type UseContext {
        BigDecimal[1..1] id = cat_root_cat_object_map.id;

        Category[0..n] rootCategory =join cat_root_cat_object_map.category_id
                                       to cat_categories.category_id;
        ACSObject[0..n] categoryOwner = join cat_root_cat_object_map.object_id
                                          to acs_objects.object_id;

        String[0..1] useContext = cat_root_cat_object_map.use_context;

        unique (categoryOwner, useContext);
        object key (id);
    }

This essentially turns a two-way association into a full-blown object
type.  The nasty gotcha that tripped me up more than once is that when
you go from "association" to "object type", multiplicities change.
Thus, correct multiplicities for "rootCategory" and "categoryOwner"
should have been as follows:

  Model 2b:
    object type UseContext {
        BigDecimal[1..1] id = ...

        Category[1..1] rootCategory = ..
        ACSObject[1..1] categoryOwner = ..

        String[0..1] useContext = ...

        unique (categoryOwner, useContext);
        object key (id);
    }

Arguably, persistence should have recognized that the author of Model
2a is on crack.  It's physically impossible to have more than one
"rootCategory" attribute for UseContext in model 2a.  Same for
"categoryOwner".  Thus, both "[0..n]" multiplicities are obviously
incorrect.

So, there are two actionable items in this ticket (one of which we may
want to split out into a separate ticket, should we decide that both
need to be addressed).

 1. Document the associtation-to-object-type refactoring in a
    tutorial.  Stress the fact that multiplicities change.

 2. Add a YouAreOnCrackException to persistence that is thrown for
    Model 2b (and possibly other cases as well).