Skip to Content.
Sympa Menu

notify-dpml - r1912 - trunk/central/site/src/docs/metro/component/semantics

notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

Chronological Thread  
  • From: mcconnell at BerliOS <mcconnell AT mail.berlios.de>
  • To: notify-dpml AT lists.ibiblio.org
  • Subject: r1912 - trunk/central/site/src/docs/metro/component/semantics
  • Date: Wed, 14 Mar 2007 08:48:05 +0100

Author: mcconnell
Date: 2007-03-14 08:48:05 +0100 (Wed, 14 Mar 2007)
New Revision: 1912

Modified:
trunk/central/site/src/docs/metro/component/semantics/context.xml
Log:
addition of documentation about Context semantics

Modified: trunk/central/site/src/docs/metro/component/semantics/context.xml
===================================================================
--- trunk/central/site/src/docs/metro/component/semantics/context.xml
2007-03-14 06:41:26 UTC (rev 1911)
+++ trunk/central/site/src/docs/metro/component/semantics/context.xml
2007-03-14 07:48:05 UTC (rev 1912)
@@ -12,10 +12,157 @@
<section name="Component Context">

<p>
+ Under Metro all dependencies of a component are expressed using
+ a context interface. The Metro runtime will evaluate the interface,
+ build an implementation, and populate the implementation taking into
+ account data supplied under a deployment directive, together with
+ datatype and option/required status of respective context entries.
</p>

+ <subsection name="Key Terms">
+
+ <table>
+ <tr>
+ <td>context</td>
+ <td>an interface (or implementation) referenced as a component
+ constructor parameter defining the dependencies (resources and
+ services) that a component has on its environment</td>
+ </tr>
+ <tr>
+ <td>entry</td>
+ <td>a context interface is composed of a series of accessor
+ methods - each method reflects the entry name plus the "get"
+ prefix</td>
+ </tr>
+ <tr>
+ <td>nesting</td>
+ <td>a nested context is a context entry that has a return type
+ that is a context interface</td>
+ </tr>
+ <tr>
+ <td>annotation</td>
+ <td>an annotation used to mark an interface as compliant with
+ the context contract</td>
+ </tr>
+ <tr>
+ <td>contract</td>
+ <td>the rules and constraints applicable to a context interface
+ (see below)</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Context Contract">
+
+ <p>
+ A context interface is identfied using either of the following:
+ </p>
+
+ <ol>
+ <li>Explicit assertion using the <a
href="../annotation/context.html">
+ context annotation</a> marker.</li>
+ <li>Implicitly resolved by locating an inner interface with the
+ target component class named <tt>Context</tt>.</li>
+ </ol>
+
+ <p>
+ The context interface may declare 0 or more accessor methods
(subject to the
+ following constraints) where each method establishes a logical
context entry.
+ </p>
+
+ <ol>
+ <li>A method may not declare the <tt>void</tt> return type (the
Metro
+ runtime fully supports primative, complex, and array return
types).</li>
+ <li>An entry method with zero parameters is deemed to be a
required entry.</li>
+ <li>Entry methods declaring a single parameter are deemed to be
optional
+ entries. The parameter type of an optional entry must be
assignable to the
+ method return type.</li>
+ <li>Entry methods may not declare exceptions.</li>
+ </ol>
+
+ <p>
+ Each method signature is used to resolve the following feature of
the respective context
+ entry
+ </p>
+
+ <table>
+ <tr>
+ <td>name</td>
+ <td>resolved using Java Bean method naming conventions
+ (i.e. a method named <tt>getKeystore</tt> identifies an entry
named "keystore")</td>
+ </tr>
+ <tr>
+ <td>type</td>
+ <td>the method return type identified the class of the object
associated
+ with the context entry</td>
+ </tr>
+ <tr>
+ <td>optional</td>
+ <td>the optional or required status of the entry is resolved by
the presence or
+ absence of a method parameter - if the method takes a single
parameter, the entry is
+ classed as optional, whereas a method without a parameter is
classes as a
+ non-optional entry</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Separation of requirements from solutions">
+
+ <p>
+ Context interface declare the dependencies that a component
+ has on its environment. The solution to these dependecy constraints
+ are handled via <a href="../profile/index.html">packaged profiles</a>
+ and/or independent <a href="../directive/index.html">deployment
directives</a>.
+ </p>
+
+ </subsection>
+
</section>
-
+
+ <section name="Examples">
+
+ <subsection name="Simple Example">
+
+ <p>
+ The following example demonstrates the declaration of a context via
+ the implicit inner-interface pattern (i.e. an inner interface named
Context).
+ The context interface declare four entries - "count", "label",
+ "backgroundColor" and "gizmo". The count and gizmo entries are
non-optional
+ whereas the remaining two entries are classes as optional. At
runtime a
+ container is required to construct and populate the supplied context
implementation
+ ensuring that all non-optional entries have resolvable values. A
container may
+ provide values for non-optional entries, however client code may
assume that client
+ supplied argument may be returned back to the client.
+ </p>
+
+<pre>
+public class Widget
+{
+ <font color="darkred">public interface Context
+ {
+ int getCount();
+ String getLabel( String value );
+ Color getBackgroundColor( Color color );
+ Gizmo getGizmo();
+ }</font>
+
+ public Widget( <font color="blue">final Context context</font> )
+ {
+ int count = context.getCount();
+ String label = context.getLabel( "Hello" );
+ Color color = context.getBackgroundColor( Color.RED );
+
+ ...
+
+ }
+}</pre>
+
+ </subsection>
+
+ </section>
+
</body>

</document>




  • r1912 - trunk/central/site/src/docs/metro/component/semantics, mcconnell at BerliOS, 03/14/2007

Archive powered by MHonArc 2.6.24.

Top of Page