APAM/APAM REFERENCE CARD
From Wiki Adele Team
This APAM Wiki is no longer maintained. Please switch to the following github Wiki for newest APAM information:
http://github.com/AdeleResearchGroup/ApAM/wiki
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...!