Changes between Version 5 and Version 6 of Java API

Show
Ignore:
Timestamp:
09/05/12 16:23:50 (13 years ago)
Author:
jorisborgdorff
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Java API

    v5 v6  
    1616=== Conduits === 
    1717 
    18 The conduit is the mechanism in the MUSCLE runtime environment to send data. In the API, the ConduitEntrance and ConduitExit are accessible. The ConduitEntrance is used to send data, while the ConduitExit receives data. These entrances and exits, as we call them, can be accessed in two ways. Either they are created in the addPortals() method, or they are called on the fly in the code using the out() and in() methods. 
    19  
    20 The addPortals method is called before the submodel starts, so the exits and entrances are stored as fields of your class. The conduit exit and entrance uses Java Generics to define what kind of data will be received or sent, both in the field declaration and in the addExit or addEntrance method. This allows for compile-time and run-time checking of data that is sent over the conduit. 
     18The conduit is the mechanism in the MUSCLE runtime environment to send data. In the API, the {{{ConduitEntrance}}} and {{{ConduitExit}}} are accessible. The {{{ConduitEntrance}}} is used to send data, while the {{{ConduitExit}}} receives data. These entrances and exits, as we call them, can be accessed in two ways. Either they are created in the {{{addPortals()}}} method, or they are called on the fly in the code using the {{{out()}}} and {{{in()}}} methods. 
     19 
     20The {{{addPortals()}}} method is called before the submodel starts, so the exits and entrances are stored as fields of your class. The conduit exit and entrance uses Java Generics to define what kind of data will be received or sent, both in the field declaration and in the addExit or addEntrance method. This allows for compile-time and run-time checking of data that is sent over the conduit. 
    2121{{{ 
    2222ConduitExit<double[]> exitA; 
    … …  
    2929} 
    3030}}} 
    31 To send or receive, use the fields that were initialized in addPortals(). 
     31To send or receive, use the fields that were initialized in {{{addPortals()}}}. 
    3232{{{ 
    3333double[] dataA = exitA.receive(); 
    … …  
    3535}}} 
    3636 
    37 If addPortals() is not overridden it is possible to use the out() and in() methods to send or receive data. It is then not necessary to store the ConduitExit and ConduitEntrance as a field. 
     37If {{{addPortals()}}} is not overridden it is possible to use the out() and in() methods to send or receive data. It is then not necessary to store the {{{ConduitExit}}} and {{{ConduitEntrance}}} as a field. 
    3838{{{ 
    3939double[] dataA = (double[]) in("exitName").receive(); 
    4040out("entranceName").send(dataA); 
    4141}}} 
    42 In this case received data needs to be cast to double[] to use it, and in the send statement, the Java compiler will give a warning that an unchecked conversion is being done. If the cast is not correct, a ClassCastException will be thrown by Java. If the exit or entrance name is not configured, an IllegalArgumentException will be thrown by MUSCLE. 
     42In this case received data needs to be cast to {{{double[]}}} to use it, and in the send statement, the Java compiler will give a warning that an unchecked conversion is being done. If the cast is not correct, a {{{ClassCastException}}} will be thrown by Java. If the exit or entrance name is not configured, an {{{IllegalArgumentException}}} will be thrown by MUSCLE. 
    4343 
    4444The advantage of the first method is that it is type-safe, so there is no need to cast the data. Also if the code and the configuration file do not match this is detected immediately. The advantage of the second method is that it is less verbose and leads to smaller classes. 
    4545 
    46 A ConduitExit is used for receiving in a blocking mode. There are two receive methods: receive() and receiveObservation(). In the first case only the data is received. In the second, an observation is received, which contains the data but also the timestamp at which the data was sent, and the timestamp at which the next message will arrive. So, 
     46A {{{ConduitExit}}} is used for receiving in a blocking mode. There are two receive methods: {{{receive()}}} and {{{receiveObservation()}}}. In the first case only the data is received. In the second, an observation is received, which contains the data but also the timestamp at which the data was sent, and the timestamp at which the next message will arrive. So, 
    4747{{{ 
    4848double[] dataA = exitA.receive(); 
    … …  
    7474=== Parameters === 
    7575 
    76 Parameters that are defined in the configuration file are accessed through a range of get*Property() methods. The most basic form is 
     76Parameters that are defined in the configuration file are accessed through a range of {{{get*Property()}}} methods. The most basic form is 
    7777{{{ 
    7878String parameter = getProperty("propName"); 
    7979}}} 
    80 In this form the property is read as a string. It first tries to find the instance property by searching for "instanceName:propName" and then for a global property named "propName". All get*Property() methods will throw an IllegalArgumentException if the property does not exist, this can be prevented by first calling hasProperty(). 
     80In this form the property is read as a string. It first tries to find the instance property by searching for "instanceName:propName" and then for a global property named "propName". All {{{get*Property()}}} methods will throw an {{{IllegalArgumentException}}} if the property does not exist, this can be prevented by first calling {{{hasProperty()}}}. 
    8181If a instance property is specifically required, this can be checked by first calling 
    8282{{{ 
    … …  
    9191}}} 
    9292 
    93 To get other types of parameters than strings, use getPathProperty for a File, getIntProperty for an int, getDoubleProperty for a double and getBoolProperty for a boolean. 
     93To get other types of parameters than strings, use {{{getPathProperty()}}} for a {{{File}}}, {{{getIntProperty()}}} for an {{{int}}}, {{{getDoubleProperty()}}} for a {{{double}}} and {{{getBoolProperty()}}} for a {{{boolean}}}. 
    9494 
    9595== MUSCLE MML API == 
    … …  
    262262}}} 
    263263 
    264 With MUSCLE a DoubleFileSink, NullFileSink and a DoubleFileSource are provided in the {{{muscle.core.conduit.terminal}}} package. Also the abstract classes FileSource and FileSink are available to override. See the API documentation for more information. 
     264With MUSCLE a {{{DoubleFileSink}}}, {{{NullFileSink}}} and a {{{DoubleFileSource}}} are provided in the {{{muscle.core.conduit.terminal}}} package. Also the abstract classes {{{FileSource}}} and {{{FileSink}}} are available to override. See the API documentation for more information. 
    265265 
    266266== MUSCLE free-form API ==