projecthydra/active_fedora — pull request #207 by scande3 (2013-09-18 18:02:18+00:00)
Title: Support for extended cmodels (read-only)

In Active Fedora, it assumes quite often that a given object will have
only a single valid content model. With models in the community
starting to extend from other models (ie. Sufia or internal models at
BPL), this update makes such cases more sane. Note that this
functionality is only for reading of objects.

For the below bulleted examples, I will assume the following two
models:

class GenericFile << ActiveFedora::Base

class ExtendedGenericFile << GenericFile

* belongs_to and has_many should automatically cast objects based on
the base class_name. For example, if one has:

```
has_many files, class_name: "GenericFile"
```

In this case, "GenericFile" objects will still be returned as such.
But "ExtendedGenericFile" objects will be instantiated as that
class. Note that only the first cmodel order on the
"ExtendedGenericFile" object is not important as it will attempt
to use the most specific class available.

* adapt_to_cmodel no longer blindly uses the first cmodel. If an object
of a class other than ActiveFedora::Base is called with it, it will
attempt to find a more specific model based on that base model. If
no more specific model is found, it will return itself.

Otherwise, if the object is loaded of type ActiveFedora::Base,
it will use the first model, and cast as that unless it finds
a more specific model registered in the system (based on that
first model it finds).

* As these are read-only support, relationships are not written
upon creation. So, to best use these, if one instantiates an
extended cmodel, one should create the cmodel inheritance in
their own code at some point. To do this, some psuedo-code
one needs to do during object creation is:

```
object_superclass = self.class.superclass
until object_superclass == ActiveFedora::Base
|| object_Superclass == Object do
add_relationship(:has_model, object_superclass.to_class_uri)
object_superclass = object_superclass.superclass
end
```

It is ideal to place this in overriding "assert_content_model"
that is only called on initial object creation.

NOTE: This is not needed to use these changes in most cases.
It only affects locating extended objects in relationships
defined as their superclass. For example, using the objects
above, :has_many of type "GenericFile" won't find
"ExtendedGenericFile" objects without actually persisting this
inheritence. This is not an issue if one isn't attempting to
use extended cmodels (ie. rather than extending GenericFile
one simply keeps the same name and overwrites it in their system,
as is done in WGBH's DAM system).