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(), andfalse
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(), andfalse
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 eithertrue
if the client is allowed to subscribe to that subject orfalse
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