For release notes for previous versions, please see Release History

2.1.0

30th October 2018

This is a major release, featuring improvements to data output, messaging APIs and scenario execution.

Insert summary and links to 2.1 headline features here.

Migrating to 2.1 from 2.0.x

Messaging API Changes

The sendMessage and broadcastMessage APIs have been reworked, and the way Message and Link types are defined and retrieved have also been updated.

BlankLink removal

The default link type BlankLink has been removed, and so when constructing links via connectors you will now always need to define and declare your link type. This has been done to encourage the good modelling practice of naming the relations you are defining, as this can become confusing when transitioning from simple models to more complicated ones.

Messaging API

For broadcastMessage, a new fluent API now provides the capability to filter and customise messages sent based on the link the message will be sent along. As well as this, the capability to broadcast along all link types has been removed as this was rarely the modeller's intention once multiple link types are defined, and could cause confusing and unexpected behaviour.

/// 2.0

cell.broadcastMessage(new Messages.Aliveness(cell.alive),
											Links.Neighbour.class);

// Any message received is inside a wrapper Message type
Message<Messages.Aliveness> m = cell.getMessageOfType(Messages.Aliveness.class);

/// 2.1

// Using a generic message class.
cell.getLinks(Links.Neighbour.class)
    .send(Messages.Aliveness.class, (msg, link) -> msg.alive = cell.alive);

// Using a specialised message class (shown below)
// Here the value given is assigned into the body
// of the constructed messages automatically.
cell.getLinks(Links.Neighbour.class)
    .send(Messages.Aliveness.class, cell.alive);

// New functionality, customising and filtering messages sent
// using link information.
cell.getLinks(Links.Neighbour.class)
    /* filter messages sent based on link */
		.filter(link -> link.property < 100)
    /* can set message body based on link attributes */
    .send(Messages.Aliveness.class,
          (msg, link) -> msg.setBody(link.property > some_condition));

// Any message received is now the message type itself
Messages.Aliveness m = cell.getMessageOfType(Messages.Aliveness.class)

For direct messaging with sendMessage, the same message construction API based around Agent#send is used, but using Messaging#to to define the subsequent destination.

// 2.0
cell.sendMessage(new Messages.Aliveness(cell.alive), sender)

// 2.1
cell.send(Messages.Aliveness.class, cell.alive).to(sender)

Message and Link classes

User-defined message and link types should now extend the built-in Message and Link classes. These classes should not define any constructor that requires parameters. There are also builtin special classes for messages containing a single primitive, e.g. Message.Boolean, Message.Double, etc. When using these types, there is a convenient shorthand when constructing messages, as shown above.

// 2.0
public class Messages {
  public static class Aliveness {
    public boolean alive;

    public Aliveness(boolean alive) {
      this.alive = alive;
    }
  }
}

// 2.1
public class Messages {
  // Generic Message
	public static class Aliveness extends Message {
		public boolean alive;
	}

  // Extending the special message class
  public static class Aliveness extends Message.Boolean {}
}

Links should similarly extend the Link class. There is a single specialisation of link currently, Link.Empty, that may provide optimisation benefits in the future.

Licensing

The Simudyne SDK now requires an individually issued license file in order to function. These license files should be requested from Simudyne. Detailed information on licensing restrictions for the SDK can be seen under Licensing Documentation.