This extension Application Programming Interface (API) contains all the necessary operations for building authorization plugins for the MigratoryData server to perform entitlement checks.

Before reading this manual, it is recommended to read the Architecture guide.

Main Interface

interface MigratoryDataAuthorizationListener | This interface provides all necessary methods for authenticating and controlling data access for any client that attempts to connect to the MigratoryData server to consume and publish realtime data.

interface MigratoryDataAuthorizationListener

This interface provides all necessary methods for authenticating and controlling data access for any client that attempts to connect to the MigratoryData server to consume and publish realtime data.

Note: In order to enable this interface, set the parameter Entitlement of the MigratoryData server on Custom. See more details about this parameter at: https://migratorydata.com/docs/migratorydata/configuration/core-parameters/#entitlement

The source code of an off-the-shelf authorization plugin using this interface, easy to adapt to your more specific needs, is available at: https://github.com/TODO

Summary

Members Descriptions
public void onClientConnect(EventConnect event) Called whenever a client attempts to connect to the MigratoryData server.
public void onClientUpdateToken(EventUpdateToken event) Called whenever the token of a client has been renewed.
public void onClientSubscribe(EventSubscribe event) Called whenever a client attempts to subscribe to one or more subjects.
public void onClientPublish(EventPublish event) Called whenever a client attempts to publish a message.
public void onClientDisconnect(EventDisconnect event) Called whenever a client disconnects from the MigratoryData server.
public void onInit() Called when the MigratoryData server starts and after the extension is loaded.
public void onDispose() Called when the MigratoryData server is about to stop.

Members

public void onClientConnect(EventConnect event)

Called whenever a client attempts to connect to the MigratoryData server.

Parameters

  • event a connect event

public void onClientUpdateToken(EventUpdateToken event)

Called whenever the token of a client has been renewed.

Parameters

  • event a token update event

public void onClientSubscribe(EventSubscribe event)

Called whenever a client attempts to subscribe to one or more subjects.

Parameters

  • event a subscribe event

public void onClientPublish(EventPublish event)

Called whenever a client attempts to publish a message.

Parameters

  • event a publish event

public void onClientDisconnect(EventDisconnect event)

Called whenever a client disconnects from the MigratoryData server.

Parameters

  • event a disconnect event

public void onInit()

Called when the MigratoryData server starts and after the extension is loaded.

The implementation of this method should initialize all the resources used by your authorization plugin.

public void onDispose()

Called when the MigratoryData server is about to stop.

The implementation of this method should stop your authorization plugin and dispose its resources.

namespace client

Summary

Members Descriptions
class StatusNotification This class represents a status notification to be sent to the client.
interface Client This interface provides access to various information about a client which connects to the MigratoryData server, including its entitlement token and IP address, as well as support for sending a status notification to the client and disconnecting the client.
interface EventConnect Event received when a client attempts to connect to the MigratoryData server.
interface EventDisconnect Event received when a client disconnects from the MigratoryData server.
interface EventPublish Event received when a client attempts to publish a message to the MigratoryData server.
interface EventSubscribe Event received when a client attempts to subscribe to one or more subjects in the MigratoryData server.
interface EventUpdateToken Event received when a client disconnects from the MigratoryData server.

class StatusNotification

This class represents a status notification to be sent to the client.

Summary

Members Descriptions
public inline StatusNotification(String status, String info) Constructs a new status notification.
public inline String getStatus() Returns the type of the status notification.
public inline String getInfo() Returns the detailed information of the status notification.
private final String status
private final String info

Members

public inline StatusNotification(String status, String info)

Constructs a new status notification.

Parameters

  • status a string indicating the type of the status notification

  • info a string providing the detailed information of the status notification

public inline String getStatus()

Returns the type of the status notification.

Returns

the type of the status notification

public inline String getInfo()

Returns the detailed information of the status notification.

Returns

the detailed information of the status notification

private final String status

private final String info

interface Client

This interface provides access to various information about a client which connects to the MigratoryData server, including its entitlement token and IP address, as well as support for sending a status notification to the client and disconnecting the client.

Summary

Members Descriptions
public String getToken() Returns the entitlement token of the client.
public String getClientAddress() Returns the IP address of the client.
public Map< String, Object > getAdditionalInfo() Returns additional attributes of the client as a map of key/value pairs.
public void sendStatusNotification(StatusNotification notification) Send a status notification to the client.
public void disconnect() Call this method to disconnect the client.

Members

public String getToken()

Returns the entitlement token of the client.

The value returned by this method is the entitlement token assigned to the client on the client-side with the client API method MigratoryDataClient.setEntitlementToken(String token).

Returns

the entitlement token of the client

public String getClientAddress()

Returns the IP address of the client.

Returns

the IP address of the client

public Map< String, Object > getAdditionalInfo()

Returns additional attributes of the client as a map of key/value pairs.

By default, no attributes are included.

Returns

a map with additional attributes

public void sendStatusNotification(StatusNotification notification)

Send a status notification to the client.

For example, if the token of the client is about to expire, then you can send a status notification to the client, so it can renew its token. Typically, the client will obtain a new token from the backend and will use the client API method MigratoryDataClient.setEntitlementToken(String token) to provide the new token.

Parameters

  • notification a status notification to be sent to the client

public void disconnect()

Call this method to disconnect the client.

For example, if the token of the client expires, and no renewed token is received, then the client should be disconnected using this method.

interface EventConnect

Event received when a client attempts to connect to the MigratoryData server.

Summary

Members Descriptions
public Client getClient() Returns the Client object.
public void authorize(boolean permission, String reason) Call this method to authorize or refuse the connection of the client.

Members

public Client getClient()

Returns the Client object.

Returns

the Client object

public void authorize(boolean permission, String reason)

Call this method to authorize or refuse the connection of the client.

Parameters

  • permission true to authorize the connection of the client with the credentials provided by getClient(), and false otherwise

  • reason a string containing the reason of the authorization or refusal

interface EventDisconnect

Event received when a client disconnects from the MigratoryData server.

Summary

Members Descriptions
public Client getClient() Returns the Client object.

Members

public Client getClient()

Returns the Client object.

Returns

the Client object

interface EventPublish

Event received when a client attempts to publish a message to the MigratoryData server.

Summary

Members Descriptions
public Client getClient() Returns the Client object.
public String getSubject() Returns the subject of the message to be authorized for publication.
public void authorize(boolean permission) Allows or denies the authorization request for message publication.

Members

public Client getClient()

Returns the Client object.

Returns

the Client object

public String getSubject()

Returns the subject of the message to be authorized for publication.

Returns

the subject of the message to be published

public void authorize(boolean permission)

Allows or denies the authorization request for message publication.

Parameters

  • permission true if the client with the credentials provided by getClient() is allowed to publish the message with the subject provided by getSubject(), and false otherwise.

interface EventSubscribe

Event received when a client attempts to subscribe to one or more subjects in the MigratoryData server.

Summary

Members Descriptions
public Client getClient() Returns the Client object.
public List< String > getSubjects() Returns the list of subjects to be authorized for subscription.
public void authorize(Map< String, Boolean > permissions) Allows or denies the authorization request for subscription.

Members

public Client getClient()

Returns the Client object.

Returns

the Client object

public List< String > getSubjects()

Returns the list of subjects to be authorized for subscription.

Returns

the subjects to be subscribed

public void authorize(Map< String, Boolean > permissions)

Allows or denies the authorization request for subscription.

Parameters

  • permissions a map of permissions where each of its elements consists of a key/value pair, the key is one of the subjects provided by getSubjects(), and the value is either true if the client is allowed to subscribe to that subject or false otherwise

interface EventUpdateToken

Event received when a client disconnects from the MigratoryData server.

Summary

Members Descriptions
public Client getClient() Returns the Client object.

Members

public Client getClient()

Returns the Client object.

Returns

the Client object