Futures

Akka Wamp provides you with

All operations are provided as direct method calls returning composable futures. You can write your client applications, in either Scala or Java, so to connect to routers, open sessions to attach realms, publish or subscribe to topics, consume events, register or call remote procedures and handle invocations in few liens of code.

@@@ note This shall be considered an higher level API when compared to Akka Wamp Actors as it doesn't require you to know anything about how WAMP Messages are exchanged by peers. @@@

Client

Clients are those peers that, indirectly, communicate each other through a router. The Akka Wamp client instance can be created as follows:

Scala : @@snip FuturesScalaClient{ #client }

Java : @@snip FuturesJavaClient{ #client }

Just invoke the Client factory method and pass the following arguments:

  • system: ActorSystem
    Is the Akka Actor System the client needs to spawn actors and provide execution context to futures.

Connections

Clients that wish to communicate each other shall connect to the same router. The Akka Wamp client can connect to a router as follows:

Scala : @@snip FuturesScalaClient{ #connect }

Java : @@snip FuturesJavaClient{ #connect }

Just invoke the connect method and pass the following arguments:

  • endpoint: String
    Is the name of a configured endpoint (default is "local"). Read the configuration section further below.

or the following arguments:

  • address: String
    Is the address to connect to (e.g. "wss://hostname:8433/router")

  • format: String
    Is the format of messages as exchanged the wire (e.g. "msgpack")

Configuration

@@snipapplication.conf{ #client }

Disconnect

The Akka Wamp client makes a distiction between deliberate and accidental disconnections. In either cases, any action performed in disconnected state will make the client throw ClientException("Disconnected")

Deliberate

Disconnection is requested on purpose as follows:

Scala : @@snip FuturesScalaClient{ #disconnect }

Java : @@snip FuturesJavaClient{ #disconnect }

Just invoke the disconnect method.

Accidental

Disconnection is not requested but suddenly happens (for example on mobile devices connected via wireless networks). The Akka Wamp client does not provide any mechanism to recover from this state. The connection object becomes useless and a new connection must be established.

@@@warning Please join the ongoing "Session Resumption" discussion as some different behaviour proposals are under review. @@@

Sessions

A realm is a routing and administrative domain, optionally protected by authentication and authorization, that holds subscriptions to topics and registrations of procedures for all clients attached to it.

A session is a transient conversation between a client and a router, running over a transport connection, that starts when the client requests to be attached to a specific realm. Attaching to a realm is also referred as "opening a session"

Open

Once got a (future of) connection, open a session over it so to attach the client to a specific realm.

Scala : @@snip FuturesScalaClient{ #open }

Java : @@snip FuturesJavaClient{ #open }

Just invoke the open method passing the following arguments:

  • realm: Uri
    Is the realm name (default is "default")

Close

Once the client doesn't need to keep the session attached, it can close it as follows:

Scala : @@snip FuturesScalaClient{ #close }

Java : @@snip FuturesJavaClient{ #close }

Just invoke the close method.

Topics

The client either publish events or subscribe to topics.

Publish

Once got a (future of) session, the client can publish an event to a topic with either "fire and forget" or "acknowldeged" pattern.

Scala : @@snip FuturesScalaClient{ #publish }

Java : @@snip FuturesJavaClient{ #publish }

Just invoke any the following overloaded methods:

  • publish
    It publishes in "fire and forget" pattern and returns no indication of what happened (neither failures).

    • topic: Uri
      Is the topic to publish to.

    • payload: Payload
      Is the outgoing event payload. Please refer to the Payloads section for further details.

  • publishAck
    It publishes with "acknowledged" pattern so to return a (future of) publication. It accepts the same arguments as above.

When publishing with "acknowledged" pattern the client can provide callbacks to be invoked upon future completion so to test against success or failure.

Scala : @@snip FuturesScalaClient{ #publication-completion }

Java : @@snip FuturesJavaClient{ #publication-completion }

Subscribe

Once got a (future of) session, the client can subscribe an lambda consumer to a topic as follows:

Scala : @@snip FuturesScalaClient{ #subscribe }

Java : @@snip FuturesJavaClient{ #subscribe }

Just invoke the subscribe method with the following arguments:

  • topic: Uri
    Is the topic to subscribe to

  • consumer
    Is a consumer callback as explained further below.

The client can provide callbacks to be invoked upon future completion so to test against success or failure.

Scala : @@snip FuturesScalaClient{ #subscription-completion }

Java : @@snip FuturesJavaClient{ #subscription-completion }

Consumer

The client can subscribe any callback function given either as an event consumer or as lambda consumer.

Please note that, as this API is build atop of Akka Wamp Actors, your callback function will be invoked in the same thread which delivers the Event message from underlying actor's mailbox. Therefore, it is safe to close your callback over free variables as there's no risk to have multiple threads executing the handler at the same time.

Lambda Consumer

The client can subscribe a lambda consumer that accepts as many parameters as it would expect to be conveyed by incoming events.

Scala : @@snip FuturesScalaClient{ #lambda-consumer }

Please refer to the Macros section for further details about how to access arguments conveyed by incoming events.

@@@warning Lambda consumers are supported for Scala only @@@

Event Consumer

The client can subscribe an event consumer as a function that accepts exactly one argument of type Event and returns (future of) Done.

Scala : @@snip FuturesScalaClient{ #event-consumer }

Java : @@snip FuturesJavaClient{ #event-consumer }

Please refer to the Payloads section for details about how to access arguments conveyed by incoming events.

Unsubscribe

Once got a (future of) subscription, the client can unsubscribe from it.

Scala : @@snip FuturesScalaClient{ #unsubscribe }

Java : @@snip FuturesJavaClient{ #unsubscribe }

Just invoke the unsubscribe method.

Procedures

The client can either call or register remote procedures.

Call

Once got a (future of) session, the client can call a remote procedure as follows

Scala : @@snip FuturesScalaClient{ #call }

Java : @@snip FuturesJavaClient{ #call }

Just invoke the call method with the following arguments:

  • procedure: Uri
    Is the remote procedure name to call

  • args
    Are the arguments to provide the invocation with

The client can provide callbacks to be invoked upon future completion so to test against success or failure.

Scala : @@snip FuturesScalaClient{ #result }

Java : @@snip FuturesJavaClient{ #result }

Register

Once got a (future of) session, the client can register a local invocation handler as endpoint of a remote procedure as follows:

Scala : @@snip FuturesScalaClient{ #register }

Java : @@snip FuturesJavaClient{ #register }

Just invoke the register method with the following arguments:

  • procedure: Uri
    Is the procedure to register.

  • handler
    Is a handler as explained further below.

The client can provide callbacks to be invoked upon future completion to test against success or failure.

Scala : @@snip FuturesScalaClient{ #registration }

Java : @@snip FuturesJavaClient{ #registration }

Handler

The client can register any callback function given either as an invocation handler or as lambda handler.

Please note that, as this API is build atop of Akka Wamp Actors, your callback function will be invoked in the same thread which delivers the Invocation message from underlying actor's mailbox. Therefore, it is safe to close your callback over free variables as there's no risk to have multiple threads executing the handler at the same time.

Lambda Handler

The client can register a lambda handler that accepts as many parameters as you would expect to be conveyed by incoming invocations.

Scala : @@snip FuturesScalaClient{ #lambda-handler }

Please refer to the Macros section for further details about how to access arguments conveyed by incoming invocations.

@@@warning Lambda handlers are supported for Scala only. @@@

Invocation Handler

The client can subscribe an invocation handler as a function that accepts exactly one argument of type Invocation and returns a (future of) Payload.

Scala : @@snip FuturesScalaClient{ #invocation-handler }

Java : @@snip FuturesJavaClient{ #invocation-handler }

Please refer to the Payloads section for futher details about how to access arguments conveyed by incoming invocations.

Unregister

Once got a (future of) registration, the client can unregister from it.

Scala : @@snip FuturesScalaClient{ #unregister }

Java : @@snip FuturesJavaClient{ #unregister }

Just invoke the unregister method.

Putting all together

Scala : @@snip FuturesScalaClient{ #all-together }

Java : @@snip FuturesJavaClient{ #all-together }