Unloaded collections/links are a pain

[jamoore]

Writing this one up under documentation. Am also adding documentation to [
​http://cvs.openmicroscopy.org.uk/tiki/tiki-index.php?page=Omero+Object+Model Omero+Object+Model] on the tiki.

As seen in:

• #92
• #60
• #194
• #141
• #143
• #208
• ...

the fact that collections can get unloaded (set to null) or filtered (have their name add to Details.filteredSet()) is very difficult for users. Calls to link<Class> or unlink<Class> fail mysteriously. The simplest solution is to take the checks in the model classes a step further (this is actually the defect here) and check filtered as well as null.

All calls no matter what throw an exception. This then needs to be documented in the API calls that the graphs that are returned "will throw an IllegalStateException when someObject.getSomeOtherObject() is called". Users of the generic IUpdate and IQuery should be equally forewarned.

The only alternative really is to not lazily load our collections. This isn't too bad until the case comes that a dataset with 10,000 images should be returned, but the user doesn't care about the images.

More sensible is to clarify the add<Class>/link<Class>/etc. model API and to make the exceptions as understandable as possible. (In the special case of links, #208 is also important.)

[jmoore]

Note also need to examine the difference between what the read filter does and manual filtering. Read filter does not_ update the filtered set!

[hflynn]

This is covered in the developer docs these days, isn't it? I'm sure I saw something along these lines while editing recently. Can we close this?

[jmoore]

Likely the state of the code isn't as well-documented as it should be, nor is the state of the docs as up-to-date as it should be, but there isn't a concrete TODO here other than just going through all the docs, so happy to close.