Server - Lanes

Swim developer logo developer.

Overview


Lanes are members of Services. A Lane has the following features:

  • Can (usually) store data, unless it is a CommandLane.
  • Data stored internally in Recon.
  • Contains execution code in its callbacks.
  • Has a relative URI which is resolved into a fully qualified URI by pre-pending the URI of it's parent Service.
  • Accessible via DownLinks from any SWIM context, including other Services and a SwimClient.
  • Persistent (i.e data is retained upon application/service restart) by default, but can be configured to be transient to keep data solely in memory.
  • Is a parameterized class. Any class type can be specified provided there is a Recon transformation to/from that class.

The most prominent lane types are

  1. ValueLane: Stores a single item and is accessed with a ValueDownlink. Developers can override callback functions that execute when the `ValueLane` is updated or about to be updated.
  2. MapLane: Stores a key-value map and is accessed with MapDownlink. Developers can override callback functions that execute when the MapLane is updated or about to be updated.
  3. CommandLane: A stateless lane for taking action and invoked with commands. Developers can override call-back functions that execute when the CommandLane is invoked.
  4. JoinValueLane: Aggregates multiple ValueDownlinks in a single lane. Automatically re-links to its aggregated lanes if a service restarts.
  5. JoinMapLane: Aggregates multiple MapDownlinks in a single lane. Automatically re-links to its aggregated lanes if a service restarts.

The callback functions for a given Lane can directly access data from other Lanes in the same Service instance. However, these functions can also read from, write to, and command Lanes in any Swim Service, including those in a different Plane, by using the aforementioned Swim API.

ValueLane

ValueLane stores a single item and is accessed with ValueDownlink. A ValueLane is perfect for storing a single value or object.

Definition

ValueLanes are defined within a Swim Service.

@SwimRoute("/planet/:name") class PlanetService extends AbstractService { @SwimLane("co2") ValueLane co2 = valueLane() .didSet((Value newCo2Value, Value oldCo2Value) -> { // invoked when a new value is set on this lane // perform business logic here including setting other value lanes or updating other map lanes as necessary }); }
  • HTML
  • recon

Setting a value of a ValueLane is easy when working inside the same Service as the Lane --simply call lane.set(value).

MapLane

MapLane stores a key-value map and is accessed with MapDownlink. A MapLane is perfect for storing a multiple values that can be keyed.

Definition

MapLanes are defined within a Swim Service.

@SwimRoute("/planet/:name") class PlanetService extends AbstractService { @SwimLane("co2History") MapLane co2History = mapLane() .keyForm(Form.LONG) // must specify when the key is not Value.FORM .didUpdate((Long timestampKey, Value newCo2Value, Value oldCo2Value) -> { // invoked when a the lane gets updated with a (key, newValue) // perform business logic here including setting other value lanes or updating other map lanes as necessary }); @SwimLane("co2MaxByMonth") MapLane co2MaxByMonth = mapLane() .keyForm(Form.STRING) // must specify when the key is not Value.FORM .didUpdate((String monthKey, Value newCo2Value, Value oldCo2Value) -> { // invoked when a the lane gets updated with a (key, newValue) // perform business logic here including setting other value lanes or updating other map lanes as necessary }); }
  • HTML
  • recon

Updating a MapLane is easy when working inside the same Service as the Lane--simply call lane.put(key, value).

CommandLane

CommandLane is a stateless Lane suited for taking action, and is invoked with commands. A CommandLane is perfect for invoking actions on a service from other Services, or externally either via a SwimClient or from external programs (Python, C# etc.) using websocket packets.

Definition

CommandLanes are defined within a Swim Service.

@SwimRoute("/planet/:name") class PlanetService extends AbstractService { @SwimLane("addCO2") CommandLane addCO2 = commandLane().valueClass(Form.DOUBLE).onCommand(d -> { // invoked when a command is invoked // perform business logic here including setting other value lanes or updating other map lanes as }); }
  • HTML
  • recon

JoinLanes

Swim provides a higher level abstraction to use DownLinks from other Services called Joins. A Join abstraction applies to either a ValueLane or a MapLane, called JoinValueLane and JoinMapLane respectively. A JoinLane provides a streamlined means of linking to several different services and assigning to each service a common aggregation function. Please refer to the example here for a comprehensive example of JoinLanes.