Example 08 – Linkability


Linkability is the mechanism that makes it possible to create interactions among artifacts, i.e. execute inter-artifacts operations. Besides the usage interface, an artifact can expose operations – to be tagged with @LINK. These operations are meant to be called by other artifacts. In order to allow an artifact A to execute operations over an artifact B, two options are provided:

  • the artifact A must be explicitly linked to the artifact B by an agent, executing linkArtifacts action, specifying the name of an output port that the artifact A must expose. Then, operations of artifact A can execute operations of the linked artifact B by using the execLinkedOp primitive, specifying the output port where the linked artifact has been linked.
  • without linking the two artifacts, an artifact A can execute operations over the artifact B by specifying in execLinkedOp the target identifier of the artifact B.

In the following example, an agent creates and links together two artifacts. Then, it executes some operations of one artifact, the linking one, which in turns executes operations over the second one, the linked one:

MAS example08_linkability {

  environment:
  c4jason.CartagoEnvironment

  agents:
  linkability_tester agentArchClass c4jason.CAgentArch;

  classpath: "../../../lib/cartago.jar";"../../../lib/c4jason.jar";
}

Source code of the linkable artifact:

public class LinkableArtifact extends Artifact {

  int count;

  void init(){
    count = 0;
  }

  @LINK void inc(){
    log("inc invoked.");
    count++;
  }

  @LINK void getValue(OpFeedbackParam v){
    log("getValue invoked");
    v.set(count);
  }
}

Highlights:

  • @LINK operations: the semantics of linked operations is the same of normal operation.
  • Output parameters: linked operations can contain also output parameters, as normal operations.

Source code of the linking artifact:

@ARTIFACT_INFO(
  outports = {
    @OUTPORT(name = "out-1")
  }
) public class LinkingArtifact extends Artifact {

  @OPERATION void test(){
      log("executing test.");
      try {
        execLinkedOp("out-1","inc");
      } catch (Exception ex){
        ex.printStackTrace();
      }
  }

  @OPERATION void test2(OpFeedbackParam v){
      log("executing test2.");
      try {
        execLinkedOp("out-1","getValue", v);
        log("back: "+v.get());
      } catch (Exception ex){
        ex.printStackTrace();
      }
  }

  @OPERATION void test3(){
      log("executing test3.");
      try {
        ArtifactId id = makeArtifact("new_linked",
               "c4jexamples.LinkableArtifact", ArtifactConfig.DEFAULT_CONFIG);
        execLinkedOp(id,"inc");
      } catch (Exception ex){
        ex.printStackTrace();
      }
  }
}

The test and test2 operations executes respectively the inc and getValue operation over the artifact linked to the out-1 port. The operation test3 instead creates an artifact and executes a linked operation directly using artifact identifier.

Highlights:

  • Output ports: output ports are declared in the @ARTIFACT_INFO annotation of the artifact class, outports attribute;
  • Linked operation execution: the execution semantics is the same of normal operations. The execOpLinked
    primitive suspend the operation execution until the operation execution on the linked artifact has completed.

Finally, the agent source code:

!test_link.

+!test_link
  <- makeArtifact("myArtifact","c4jexamples.LinkingArtifact",[],Id1);
     makeArtifact("count","c4jexamples.LinkableArtifact",[],Id2);
     linkArtifacts(Id1,"out-1",Id2);
     println("artifacts linked: going to test");
     test;
     test2(V);
     println("value ",V);
     test3.

Highlights:

  • Linking artifacts: linkArtifact‘s parameters include the identifier of the linking artifact, its outport and the identifier of the linked artifact.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>