View source for APAM/APAM REFERENCE CARD

=APAM DSL Reference Card=

In Progress ...

ALL APAM SYNTAXE !!!

=Primitive Elements=

<source lang="xml">

<!-- Declaration of a specification -->
<specification name="HelloAndGoodbye" 
               interfaces="first.interface.Hello,second.interface.Goodbye"  
               messages="first.message.Happy,second.message.Angry">
    ....
</specification>

<!-- Declaration of the Implementation of the specification "HelloAndGoodbye" -->
<implementation name="MyImplOf-HelloAndGoodbye" 
                classname="my.classname.Mood"
                specification="HelloAndGoodbye"
                interfaces="first.interface.Hello,second.interface.Goodbye,new.interface.Cool" 
                messages="first.message.Happy,second.message.Angry,new.message.Indifferent"
                message-fields="produceHappy,produceAngry,produceIndifferent">
 ....
</implementation>

<!-- Declaration of the Instance of the implementation "MyImplOf-HelloAndGoodbye" -->
<instance name="myInstOf-HelloAndGoodbye" implementation="MyImplOf-HelloAndGoodbye">
 ....
</instance>
</source>


{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Component 
!Attribute
!Optional
!Default Value
!Description
|-
|rowspan="3"|Specification
|name
|style="color:red;text-align: center"|No
| 
|Each specification must have an unique associated name.
|-
|interfaces
|style="color:green;text-align: center"|Yes
|
|List of service interfaces provided by this specification
|-
|messages
|style="color:green;text-align: center"|Yes
|
|Messages(or events) provided by this specification
|-
|rowspan="6"|Implementation
|name
|style="color:green;text-align: center"|Yes (if <br/>classname defined)
|Can be extracted<br/>from java classname 
|Each implementation must have an associated name.
|-
|classname
|style="color:green;text-align: center"|Yes
|
|The name of the Java class of this implementation
|-
|specification
|style="color:green;text-align: center"|Yes
|
|The specification provided by this implementation
|-
|interfaces
|style="color:green;text-align: center"|Yes
|all implemented interfaces <br/> in the java classname
|Defines the interface provided by this implementation.
|-
|messages
|style="color:green;text-align: center"|Yes
|all types of message-fields <br/> in the java classname
|Defines the interface produced by this implementation
|-
|message-fields
|style="color:green;text-align: center"|Yes
|
|Defines the interface produced by this implementation
|-
|rowspan="2"|Instance
|name
|style="color:green;text-align: center"|Yes
|generated from the <br/> implementation name
|Each instance must have an associated name.
|-
|implemetation
|style="color:red;text-align: center"|No
|
|Defines the implementation of this instance.
|}



==Definitions and Properties==

<source lang="xml">
 <!-- "HelloAndGoodbye" with definitions and properties -->
 <specification name="HelloAndGoodbye" ... >
    <definitions>
       <definition name="language" type="string" value="arabic"/>
    </definitions>
    <properties>
       <property name="vendor" value="AdeleResearchGroup" type="boolean"/>
    </properties>
 </specification>

 <!-- "MyImplOf-HelloAndGoodbye" with definitions and properties -->
 <implementation name="MyImplOf-HelloAndGoodbye" ...>
    <definitions>
      <definition name="version" type="string" field="version" value="0.1.0"/>
    </definitions>
    <properties>
       <property name="language" value="french" />
    </properties>
 </implementation>

 <!-- "myInstOf-HelloAndGoodbye" with properties -->
 <instance name="myInstOf-HelloAndGoodbye" ...>
    <properties>
       <property name="version" value="1.2.3" />
    </properties>
 </instance>

</source>

{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Concept
!Attribute
!Optional
!Default Value
!Description

|-
|rowspan="4"| Definition
|name
|style="color:red;text-align: center"|No
|the field name <br/>(if it's declared)
|the name of the defined property. 
|-
|type
|style="color:red;text-align: center"|No
|
|the type of the defined property.
|-
|field
|style="color:green;text-align: center"|Yes
|
|(ONLY in implementation component) an associated field. <br/> this field will be injected by the value of the property.
|-
|value
|style="color:green;text-align: center"|Yes
|the field value <br/>(if it's declared)
|the default value of the defined property,this value can <br/>be overridden in the implementation if it is defined in the <br/>specification or in the instance of it is defined in the instance
|-
|rowspan="2"|Property
|name
|style="color:red;text-align: center"|No
|
|the name of a previous defined property. <br/>Exept in specification, properties must be defined in the high <br/>level component. 
|-
|value
|style="color:red;text-align: center"|No
|
|a value for the property. All defined property must <br/>be "valued" in the next component, exept definition<br/> with default value or with a declared field.
|}

==Dependencies==

<source lang="xml">
  <!-- "HelloAndGoodbye" with dependencies -->
<specification name="HelloAndGoodbye" ... >
  ...
  <dependency specification="SpeechInterpreter" id="speech-dep">  ...  </dependency>
  <dependency interface="fr.imag.Dictionary"  id="dico-dep">     ...  </dependency>
  <dependency message="fr.imag.Sentence"  id="sentence-dep">    ...   </dependency>
  ...
</specification>
 
 <!-- "MyImplOf-HelloAndGoodbye" with dependencies -->
<implementation name="MyImplOf-HelloAndGoodbye" ...>
  ...
  <dependency specification="SpeechInterpreter" id="speech-dep">  ...  </dependency>
  <dependency interface="fr.imag.Dictionary"  id="dico-dep">     ...  </dependency>
  <dependency message="fr.imag.Sentence"  id="sentence-dep">    ...   </dependency>
  <dependency specification="SpellChecker"  id="spell-impl-dep">    ...   </dependency>
  ...
</implementation>
 
 <!-- "myInstOf-HelloAndGoodbye" with dependencies-->
<instance name="myInstOf-HelloAndGoodbye" ...>
  ...
  <dependency specification="SpeechInterpreter" id="speech-dep">  ...  </dependency>
  <dependency interface="fr.imag.Dictionary"  id="dico-dep">     ...  </dependency>
  <dependency message="fr.imag.Sentence"  id="sentence-dep">    ...   </dependency>
  <dependency specification="SpellChecker"  id="spell-impl-dep">    ...   </dependency>
  //Instance cannot define more dependencies than implementation
  ...    
</instance>
</source>


{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Dependency
!Attribute
!Optional
!Default Value
!Description

|-
|rowspan="2"| Specification
|specification name
|style="color:red;text-align: center"|No
|
|a specification name is Required.
|-
|id
|style="color:green;text-align: center"|Yes
|calculated using the <br/>name of the specification
|a unique identifier for the dependency, it will be use <br/> to reference and specialize the dependency. 
|-
|rowspan="2"|Interface
|interface name
|style="color:red;text-align: center"|No
|
|an interface name is Required.
|-
|id
|style="color:green;text-align: center"|Yes
|calculated using the <br/>name of the specification
|a unique identifier for the dependency, it will be use <br/> to reference and specialize the dependency.
|-
|rowspan="2"|Message
|message name
|style="color:red;text-align: center"|No
|
|a message name is Required.
|-
|id
|style="color:green;text-align: center"|Yes
|calculated using the <br/>name of the specification
|a unique identifier for the dependency, it will be use <br/> to reference and specialize the dependency.
|}


=== Field and Method injection ===

''' ONLY IN IMPLEMENTATION '''

<source lang="xml">

 <!-- "MyImplOf-HelloAndGoodbye" with dependencies -->
<implementation name="MyImplOf-HelloAndGoodbye" ...>
  ...
  <dependency ... >
     ...
    <field name="dictionary" interface="fr.imag.Dictionary"/>   
    <field name="interpreter" message="fr.imag.SpeechInterpreter"/>
    <method name="unwiredDico" type="unwire" interface="fr.imag.Dictionary"/>
    <method name="newSentence"  message="fr.imag.Sentence"/> 
     ...
  </dependency>
    ...
</implementation>
</source>
<source lang="java">
package my.classname;
...
public class Mood implements Hello,Goodbye,Cool{

  /**
  *Fields injected by the framework.
  */
  private Dictionary dictionary;

  private AbstractConsumer<SpeechInterpreter> interpreter;
  ...

 /**
  *Methods injected by the framework.
  */
  public void unwiredDico(dictionary dico) {
        //...
  }

  public void newSentence(Sentence sentence) {
        //...
  }
    
    
}
</source>


{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Injection
!Attribute
!Optional
!Default Value
!Description

|-
|rowspan="3"| Field
|name
|style="color:red;text-align: center"|No
|
|the name of the field in the associated Java class.
|-
|interface
|style="color:green;text-align: center"|Yes
|the type of the <br/>declared field
|The type of the required interface  
|-
|message
|style="color:green;text-align: center"|Yes
|Extracted from the field<br/>of producer or consumer.
|The type of the message to produce or to consume 
|-
|rowspan="4"| Method
|name
|style="color:red;text-align: center"|No
|
|the name of the method in the Java class.
|-
|type
|style="color:green;text-align: center"|Yes
|wire
|(Used only for interface)type maybe wire, unwire, modified.<br/>In the case of wire, the method will be called after the wire creation.
|-
|interface
|style="color:green;text-align: center"|Yes
|type of the method argument
|the type of the required interface.
|-
|message
|style="color:green;text-align: center"|Yes
|type of the method argument
|the type of the required message.
|}

=== Constraints ===

<source lang="xml">
  <!-- "HelloAndGoodbye" with constraints -->
<specification name="HelloAndGoodbye" ... >
  ...
  <dependency id="dico-dep" ...>
   ...  
   <constraints>
      <implementation filter="(language=french)"/>
      <instance filter="(vendor=larousse)"/>
    </constraints>
   ...
   </dependency>
  ...
</specification>
 
 <!-- "MyImplOf-HelloAndGoodbye" with constraints-->
<implementation name="MyImplOf-HelloAndGoodbye" ...>
  ...
  <dependency id="dico-dep"...>
  ...   
    <constraints>
      <implementation filter="(font=italic)"/>
      <instance filter="(police=comics)"/>
    </constraints>
  ...     
  </dependency>
  ...
</implementation>
 
 <!-- "myInstOf-HelloAndGoodbye" with constraints-->
<instance name="myInstOf-HelloAndGoodbye" ...>
 ...
 <dependency id="dico-dep"...>   
   ...
   <constraints>
     <implementation filter="(implementation.name=lig.dico)"/>
     <instance filter="(spellchecker=oxford)"/>
   </constraints>
   ...        
  </dependency>
  ...
</instance>
</source>



{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Constraint
!Attribute
!Optional
!Default Value
!Description

|-
|rowspan="1"| implementation
|filter
|style="color:red;text-align: center"|No
|
|the filter use to constraint the selection of an implementation<br/> the filter is an union of all components filter. The selected implementation must<br/>respect the constraint filter
|-
|rowspan="1"| instance
|instance
|style="color:red;text-align: center"|No
|
|the filter use to constraint the selection of an instance<br/> the filter is an union of all components filter. The selected instance must<br/>respect the constraint filter
|}

=== Preferences ===

<source lang="xml">
  <!-- "HelloAndGoodbye" , dependency with preferences-->
<specification name="HelloAndGoodbye" ... >
  ...
  <dependency id="speech-dep" ...>
   ...  
   <preferences>
      <implementation filter="(accent=spanish)"/>
      <instance filter="(vendor=DNS)"/>
    </preferences>
   ...
   </dependency>
  ...
</specification>
 
 <!-- "MyImplOf-HelloAndGoodbye" , dependency with preferences -->
<implementation name="MyImplOf-HelloAndGoodbye" ...>
  ...
  <dependency id="speech-dep"...>
  ...   
    <preferences>
      <implementation filter="(genre=male)"/>
      <instance filter="(voice=erico)"/>
    </preferences>
  ...     
  </dependency>
  ...
</implementation>
 
 <!-- "myInstOf-HelloAndGoodbye" , dependency with preferences-->
<instance name="myInstOf-HelloAndGoodbye" ...>
 ...
 <dependency id="speech-dep"...>   
   ...
   <preferences>
     <implementation filter="(version=1.0)"/>
     <instance filter="(version=1.2.0)"/>
   </preferences>
   ...        
  </dependency>
  ...
</instance>
</source>



{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Preference
!Attribute
!Optional
!Default Value
!Description

|-
|rowspan="1"| implementation
|filter
|style="color:red;text-align: center"|No
|
|if multiple implementaions satisfy the dependency (and constraints<br/>if it's declared), implementations which satisfy this filter will be prefered.
|-
|rowspan="1"| instance
|instance
|style="color:red;text-align: center"|No
|
|if multiple intances satisfy the dependency (and constraints if <br/>it's declared), instances which satisfy this filter will be prefered.
|}


== States ==


<source lang="xml">
  <!-- Defining state value in the specification-->
<specification name="HelloAndGoodbye" ... >
  ...
  <state values="{angry,happy}"/>
  ...
</specification>
 
 <!-- calculting the state value in the implementation -->
<implementation name="MyImplOf-HelloAndGoodbye" ...>
  ...
  <state field="helloState"/>
  ...
</implementation>
 

</source>



{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Compenent
!State attribute
!Optional
!Default Value
!Description

|-
|rowspan="1"| specification
|values
|style="color:green;text-align: center"|Yes
|
|The values can be set to the state.<br/>A class enum will be generated, it will be used<br/> in implementation
|-
|rowspan="1"| implementation
|field
|style="color:green;text-align: center"|Yes
|
|the value of the state will be contained in this field.<br/>The field type must be the generated class enum<br/>of the specification
|}

=Composite Elements=

<source lang="xml">
   <!-- Declaration of a  composite specification -->
<specification name="HelloCompositeSpec" ...>
  ....
  <composite>
    ....
    <main specification="HelloAndGoodbye"/> 
    ....
  </composite>
  ....
</specification>
 
<!-- Declaration of a composite implementation -->
<implementation name="HelloCompositeImpl" ...>
  ....
  <composite>
    ....
    <main implementation="MyImplOf-HelloAndGoodbye"/> 
    ....
  </composite>
  ....
</implementation>
 
<!-- Declaration of the composite instance -->
<instance name="HelloCompositeInst"...>
   ....
  <composite>
    ....
    <main instance="myInstOf-HelloAndGoodbye"/> 
    ....
  </composite>
  ....
</instance>
</source>

{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Concept
!Attribute
!Optional
!Default Value
!Description

|-
|rowspan="3"| main
|specification
|style="color:green;text-align: center"|Yes
|No main for the composite specification
|only for specification. 
|-
|implementation
|style="color:green;text-align: center"|Yes
|No main for the composite<br/>implementation, or resolved from<br/>the composite specification
|only for implementation. 
|-
|instance
|style="color:green;text-align: center"|Yes
|No main for the composite<br/>instance, or resolved from<br/>the composite implementation
|only for instance. 
|-
|}


===Definitions and Properties===

The same as primitive elements.

see section [[#Definitions_and_Properties|definitions and properties]].

===Dependencies===

The same as primitive elements.

see section [[#Dependencies|dependencies]].

=== Repositories === 
<source lang="xml">
  <!-- Declaration of an associated repository -->

  ....
  <composite>
    ....
    <repository maven="http://myremoteRepos"/>
    <repository maven="http://anotherremoteRepos"/> 
    <repository maven="file:/home/local"/> 
    ....
  </composite>
  ....

</source>

{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Concept
!Attribute
!Optional
!Default Value
!Description

|-
|rowspan="1"| repository
|maven
|style="color:green;text-align: center"|Yes
|local maven<br/>repository
|describe a maven repository to find specifications<br/>and implementations at runtime. 
|}

=== Visibilty === 
<source lang="xml">
  <!-- Setting visibility properties -->
  ....
  <composite>
    ....
    <visibility shared="true" 
                borrowImplementation="true"
                localImplementation="(specName=S2)"
                borrowInstance="false"
                localInstance="(specName=S3)" 
                appliInstance="(|(specName=S4)(specName=S.*)"/>
    ....
  </composite>
  ....
</source>

{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Concept
!Attribute
!Optional
!Default Value
!Description


|-
|rowspan="6"| Visibility
|shared
|style="color:green;text-align: center"|Yes
|true
|define if this composite can be used by more than one client
|-
|borrowImplementation
|style="color:green;text-align: center"|Yes
|true
|Defines if implementation dependencies can be<br/>resolved outside of the composite 
|-
|borrowInstance
|style="color:green;text-align: center"|Yes
|true
|Defines if instance dependencies can be resolved<br/>outside of the composite 
|-
|localImplementation
|style="color:green;text-align: center"|Yes
|
|implementation which satisfy the filter will not<br/>be visible outside the composite. 
|-
|localInstance
|style="color:green;text-align: center"|Yes
|
|instance which satisfy the filter will not<br/>be visible outside the composite.  
|-
|appliInstance
|style="color:green;text-align: center"|Yes
|
|instance which satisfy the filter will not<br/>be visible outside the application (hierachical composite). 
|}

=== States === 


<source lang="xml">
  <!-- Defining states value in the specification composite -->
<specification ... >
  ...
  <composite>
    ....
    <state values="{French,English}"/>
    ....
  <composite/>
  ...
</specification>
 
 <!-- Calculting the state in the implementation composite -->
<implementation ...>
 ...
  <composite>
    ....
    <state French="(&(SpeechInterpreter=Fr)(Dictionary=fr))">
    ....
  <composite/>
  ...
</implementation>
 

</source>


{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Compenent
!State attribute
!Optional
!Default Value
!Description

|-
|rowspan="1"| specification
|values
|style="color:green;text-align: center"|Yes
|
|The values can be set to the state.
|-
|rowspan="1"| implementation
|a state<br/>(ex: French)
|style="color:green;text-align: center"|Yes
|
|the value of the state will be contained in this field.<br/>The field type must be the generated class enum<br/>of the specification
|}

=== Actions === 
syntax fragments 

<source lang="bnf">
 type       == specification | interface | message 
 targetDef  == <type name="xx"/> | <type name="xx"> constraints </type>
 depSource  == specification="xx" | implementation="xx"
 dependency == depSource [id="ddd"]
</source>


==== Owns ====
<source lang="xml">
  <owns component=”xx”/>
  <owns component=”xx” >
      constraints
   </owns>
</source>

<source lang="xml">
  <!-- Declaration of an owns component -->
  ....
  <composite>
   ....
   <owns component="SpeechInterpreter">
     <constraints> ... </constraints>
   </owns>
   ....
  </composite>
  ....
</source>

{|class="wikitable" border="1" cellpadding="3" cellspacing="1" align="center"
!Concept
!Attribute
!Optional
!Default Value
!Description

|-
|rowspan="1"| owns
|component
|style="color:green;text-align: center"|Yes
|
|instance of this component (specification or implementation) will<br/>be contained on this composite. 
|}
===== Constraints ===== 

The same syntaxe as dependecy constraints in primitive elements.
see section [[#Constraints|Constraints]].

==== Start ====

<source lang="xml">
  <start component="xx" id="ddd" />
  <start component="xx"> targetDef </start>
</source>

<source lang="xml">
  <!-- Exemple of start action -->
  ....
  <composite>
   ....
   <start component="SpeechInterpreter" id="dep_id">
      <specification name="Sentense" >
         <constraints> ... </constraints>
      </specification>
   </start>
   ....
  </composite>
  ....
</source>

==== Wait ====
<source lang="xml">
 <wait dependency />
 <wait> targetDef </wait>
</source>

==== Grant ====
<source lang="bnf">
when == when="state" | when="( {state ,} )"
</source>

<source lang="xml">
<grant dependency when />
</source>

==== Delete ====
<source lang="xml">
  <delete dependency />
  <delete> targetDef </delete>
</source>


=== Context Properties === 


<source lang="xml">
  <!-- Defining context properties -->
  ...
  <composite>
    ....
    <context>
       <property name="language" values="Fr,Eng,Ar">
         <set value="fr">
           ....
           <component specification="Dictionary" filter="(lang=fr)"/>
           <component implementation="SpeechInterpreterImpl" filter="(lang=fr)"/>
           <component instance="SentenceInst" filter="(lang=fr)"/> 
           ....
         </set>
       </property>
        ....
    </context>
    ....
  <composite/>
  ...

</source>

set the context property language=fr when the instance of Dictionary specification, the instance of the implementation SpeechInterpreterImpl and the instance SentenceInst has a property lang=fr

in progress...!