Draft and implement a concept for single containments vs. collection containments vs. collections

[turpid-monkey]

Question: How should the following three cases behave in the generated code?

interface ClassNode {
    @Containement MethodNode getMethodNode();
}
// vs
interface ClassNode {
   Collection<MethodNode> getNodes();
}
// vs
interface ClassNode {
   @Containment Collection<MethodNode> getNodes();
}

[turpid-monkey]

To reduce semantic complexity, let's focus on a simple, real-word @containment and non-@containment collection type property.

interface Person extends Contained<Person>
{
    @Containment Collection<Person> getChildren();
    Collection<Person> getFriends();
}

For the property children, semantics are clear; child and parent have an exclusive relationship, and matches the current "@containment" characteristics. The relationship between a person and friends is a non-exclusive relationship and should be handled as such.

In order to keep the API read-only, getFriends() returns a read-only collection, while the generated class offers write access to the underlying list via getFriendsRef().

Now, in order to keep change listeners up to date, the returned reference is a variant of "ContainmentList", without the intrinsic management of the containment characteristic.

[turpid-monkey]

Another, rather simple example that challenges the current implementation of the @containment concept is posted below:

class Person implements Contained<Person>
{
    @Containment Collection<Person> getSlaves();
    @Containment Collection<Person> getKids();
}

The current implementation lacks a way to have more than one containment relation between two classes.

One way to address this is to have the Contained interface reflect the possibilty of having more than one container instances, and to generate the code to read and write all container/containee-related properties.

interface Contained<Person>
{
   Person getContainer(String propertyName);
   Collection<String> getContainmentNames();
}
/// in a different file:
public class PersonObject implements Contained<Person>
{
    Collection<Person> getSlaves() { ... }
    Collection<Person> getKids() { ... }
    ContainmentList<...,...> getSlavesRef() { ... }
    ContainmentList<...,...> getKidsRef() { ... }
}