View source for OTPattern/AssociateByNesting

==Intent==
For the sake of a particular scenario two objects need to exchange messages, but neither has a reference to the other.

==Motivation==
A particular scenario finds that one objects needs another object to perform its operation, but no reference is at hand when needed. Also the object's class cannot or should not be extended with another field, because this reference is not part of the core concern of that class. It is then tempting to dynamically create associative maps that help the object needing the service to navigate to the object providing the service. However, manually maintaining such maps is error-prone boiler plate code. 

This pattern helps if, instead of by an explicit reference chain the two objects are connected by a control flow of any depth (''In this case it might be tempting to augment method signatures for explicitly passing one object down to the other. This will, however, not work for long call-chains where at least one method exists that cannot or should not be augmented in this way for whatever reasons'').

==Structure==
This pattern maps control flow nesting to class nesting (team and role).

Consider the following base classes with an indirect control flow from <code>Base1.m1()</code> to <code>Basez.mz()</code>:
<source lang="otj">public class Base1 {
    public void m1() {
        new Base2().m2();
    }
    public void otherMethod() {/* Basez will want to call this method */}
}
public class Base2 {
    public void m2() {
        new Basez().mz(); // the call chain could involve yet more objects and methods
    }
}
public class Basez {
    public void mz() { /* at this point we need to talk to our Base1 */ }
}
</source>
This pattern superimposes a nested team:
<source lang="otj">public team class AssociateByNesting {
    protected team class Context playedBy Base1 {
        protected class Action playedBy Basez { ... }
    }
}</source>
Note, that Base2 requires no role because we abstract from the intermediate steps in the call chain.

==Participants==
The outer team '''AssociateByNesting''' only sets the stage so that the inner '''Context''' is a role and can receive callin triggers. This team '''Context''' maps to the point where the control flow ''enters'' the focus of the considered situation. Inside the Context, a role '''Action''' represents the point where communication between Base1 and Basez is required.

==Collaboration==
The collaboration is implemented like this:
<source lang="otj">public team class AssociateByNesting {
    // we assume that an instance of AssociateByNesting is globally active
    protected team class Context playedBy Base1 {
        void otherMethod() -> void otherMethod();
        callin void enter() {
            within(this)
                base.enter();
        }
        enter <- m1;
        protected class Action playedBy Basez {
            void perform() {
                Context.this.otherMethod();
            }
            perform <- after mz;
        }
    }
}</source>
# When the control flow enters the focus area at <code>Base1.m1()</code> this triggers <code>enter()</code>.
# For the duration of <code>enter()</code> including its base call (i.e., the actual m1() execution) the current instance of <code>Context</code> is temporarily activated (for this thread).
# When <code>Basez.mz()</code> finishes, the callin to <code>perform()</code> will automatically create an <code>Action</code> instance as a nested instance within the exact <code>Context</code> instance from step (2).
# Inside <code>perform()</code> the reference to the enclosing <code>Context</code> is implicitly available (<code>Context.this</code>) and using an appropriate callout binding <code>otherMethod()</code> can be invoked on the original <code>Base1</code> instance through which we entered the scenario.
 
==Variants==
If the control flow spawns additional threads the above <code>within()</code> statement is not sufficient to capture the exectution of <code>mz()</code> which may then happen in a different thread. In that case one might consider using <code>activate(ALL_THREADS)</code> (plus deactivate) instead of <code>within()</code>. In that case, care must be taken that no two instances of <code>Context</code> can be active at the same time.

==Known Uses==
This pattern was made explicit when refactoring the team <code>SamplesAdapter</code> from the <code>org.eclipse.objectteams.otdt.samples</code> plugin ([http://dev.eclipse.org/viewcvs/index.cgi/trunk/plugins/org.eclipse.objectteams.otdt.samples/src/org/eclipse/objectteams/otdt/internal/samples/SamplesAdapter.java?root=TOOLS_OBJECTTEAMS&view=markup source in SVN]). The old implementation maintained a map
<source lang="otj">
  	private Map<IConfigurationElement,SampleWizardAdapter> _wizards = new HashMap<IConfigurationElement, SampleWizardAdapter>();
</source>
Now any object holding a reference to an <code>IConfigurationElement</code> was able to obtain a reference to the role <code>SampleWizardAdapter</code> that was registered to this key.

This implementation was then refactored to use the AssociateByNesting pattern. Thus the shown map could be removed and the arbitrary use of an <code>IConfigurationElement</code> as the key was no longer needed. The required reference is now automatically present at the point where its needed. Thus even a null check could be eliminated (which was required after accessing the old map), because the nesting structure guarantees that the enclosing instance is always available.

==Related Patterns==
This pattern is similar to [[OTPattern/PerThreadRole|PerThreadRole]]

[[Category:Object Teams|AssociateByNesting]]
[[Category:Object Teams Patterns|AssociateByNesting]]