APAM/APAM REFERENCE CARD

This APAM Wiki is no longer maintained. Please switch to the following github Wiki for newest APAM information:
http://github.com/AdeleResearchGroup/ApAM/wiki

APAM DSL Reference Card

In Progress ...

ALL APAM SYNTAXE !!!

Primitive Elements

<!-- 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>

Component	Attribute	Optional	Default Value	Description
Specification	name	No		Each specification must have an unique associated name.
	interfaces	Yes		List of service interfaces provided by this specification
	messages	Yes		Messages(or events) provided by this specification
Implementation	name	Yes (if classname defined)	Can be extracted from java classname	Each implementation must have an associated name.
	classname	Yes		The name of the Java class of this implementation
	specification	Yes		The specification provided by this implementation
	interfaces	Yes	all implemented interfaces in the java classname	Defines the interface provided by this implementation.
	messages	Yes	all types of message-fields in the java classname	Defines the interface produced by this implementation
	message-fields	Yes		Defines the interface produced by this implementation
Instance	name	Yes	generated from the implementation name	Each instance must have an associated name.
	implemetation	No		Defines the implementation of this instance.

Definitions and Properties

 <!-- "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>

Concept	Attribute	Optional	Default Value	Description
Definition	name	No	the field name (if it's declared)	the name of the defined property.
	type	No		the type of the defined property.
	field	Yes		(ONLY in implementation component) an associated field. this field will be injected by the value of the property.
	value	Yes	the field value (if it's declared)	the default value of the defined property,this value can be overridden in the implementation if it is defined in the specification or in the instance of it is defined in the instance
Property	name	No		the name of a previous defined property. Exept in specification, properties must be defined in the high level component.
	value	No		a value for the property. All defined property must be "valued" in the next component, exept definition with default value or with a declared field.

Dependencies

  <!-- "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>

Dependency	Attribute	Optional	Default Value	Description
Specification	specification name	No		a specification name is Required.
	id	Yes	calculated using the name of the specification	a unique identifier for the dependency, it will be use to reference and specialize the dependency.
Interface	interface name	No		an interface name is Required.
	id	Yes	calculated using the name of the specification	a unique identifier for the dependency, it will be use to reference and specialize the dependency.
Message	message name	No		a message name is Required.
	id	Yes	calculated using the name of the specification	a unique identifier for the dependency, it will be use to reference and specialize the dependency.

Field and Method injection

ONLY IN IMPLEMENTATION

 <!-- "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>

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) {
        //...
  }
    
    
}

Injection	Attribute	Optional	Default Value	Description
Field	name	No		the name of the field in the associated Java class.
	interface	Yes	the type of the declared field	The type of the required interface
	message	Yes	Extracted from the field of producer or consumer.	The type of the message to produce or to consume
Method	name	No		the name of the method in the Java class.
	type	Yes	wire	(Used only for interface)type maybe wire, unwire, modified. In the case of wire, the method will be called after the wire creation.
	interface	Yes	type of the method argument	the type of the required interface.
	message	Yes	type of the method argument	the type of the required message.

Constraints

  <!-- "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>

Constraint	Attribute	Optional	Default Value	Description
implementation	filter	No		the filter use to constraint the selection of an implementation the filter is an union of all components filter. The selected implementation must respect the constraint filter
instance	instance	No		the filter use to constraint the selection of an instance the filter is an union of all components filter. The selected instance must respect the constraint filter

Preferences

  <!-- "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>

Preference	Attribute	Optional	Default Value	Description
implementation	filter	No		if multiple implementaions satisfy the dependency (and constraints if it's declared), implementations which satisfy this filter will be prefered.
instance	instance	No		if multiple intances satisfy the dependency (and constraints if it's declared), instances which satisfy this filter will be prefered.

States

  <!-- 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>

Compenent	State attribute	Optional	Default Value	Description
specification	values	Yes		The values can be set to the state. A class enum will be generated, it will be used in implementation
implementation	field	Yes		the value of the state will be contained in this field. The field type must be the generated class enum of the specification

Composite Elements

   <!-- 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>

Concept	Attribute	Optional	Default Value	Description
main	specification	Yes	No main for the composite specification	only for specification.
	implementation	Yes	No main for the composite implementation, or resolved from the composite specification	only for implementation.
	instance	Yes	No main for the composite instance, or resolved from the composite implementation	only for instance.

Definitions and Properties

The same as primitive elements.

see section definitions and properties.

Dependencies

The same as primitive elements.

see section dependencies.

Repositories

  <!-- Declaration of an associated repository -->

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

Concept	Attribute	Optional	Default Value	Description
repository	maven	Yes	local maven repository	describe a maven repository to find specifications and implementations at runtime.

Visibilty

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

Concept	Attribute	Optional	Default Value	Description
Visibility	shared	Yes	true	define if this composite can be used by more than one client
	borrowImplementation	Yes	true	Defines if implementation dependencies can be resolved outside of the composite
	borrowInstance	Yes	true	Defines if instance dependencies can be resolved outside of the composite
	localImplementation	Yes		implementation which satisfy the filter will not be visible outside the composite.
	localInstance	Yes		instance which satisfy the filter will not be visible outside the composite.
	appliInstance	Yes		instance which satisfy the filter will not be visible outside the application (hierachical composite).

States

  <!-- 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>

Compenent	State attribute	Optional	Default Value	Description
specification	values	Yes		The values can be set to the state.
implementation	a state (ex: French)	Yes		the value of the state will be contained in this field. The field type must be the generated class enum of the specification

Actions

syntax fragments

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

Owns

  <owns component=”xx”/>
  <owns component=”xx” >
      constraints
   </owns>

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

Concept	Attribute	Optional	Default Value	Description
owns	component	Yes		instance of this component (specification or implementation) will be contained on this composite.

Constraints

The same syntaxe as dependecy constraints in primitive elements. see section Constraints.

Start

  <start component="xx" id="ddd" />
  <start component="xx"> targetDef </start>

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

Wait

 <wait dependency />
 <wait> targetDef </wait>

Grant

when == when="state" | when="( {state ,} )"

<grant dependency when />

Delete

  <delete dependency />
  <delete> targetDef </delete>

Context Properties

  <!-- 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/>
  ...

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...!