Class EthosMessagesClient
An EthosClient used to publish and consume messages using the Ethos Integration messages service.
This client accepts an API key that belongs to an ethos application. All requests made from this client are done on behalf of the application to which that API key belongs. That means that calling the consume methods will try to retrieve change-notifications from the subscription queue of that specific application.It is assumed that the application is configured in Ethos Integration to subscribe to some resource changes.
Likewise, calling the publish methods will try to publish change-notifications on behalf of the application to which the API key belongs. It is assumed that the application is configured in Ethos Integration to own the resources that are in the change-notifications being published. If a change-notification is sent to the Ethos Integration /publish endpoint for a resource that is not owned by the calling application, it will return a
403 Forbidden
response.
The preferred way to instantiate this class is via the { @link com.ellucian.ethos.integration.client.EthosClientBuilder EthosClientBuilder }.
Inherited Members
Namespace: Ellucian.Ethos.Integration.Client.Messages
Assembly: Ellucian.Ethos.Integration.dll
Syntax
public class EthosMessagesClient : EthosClient
Constructors
EthosMessagesClient(String, HttpClient)
Creates an EthosMessagesClient using the given API key. Note that the preferred way to get an instance of this class is through the { @link com.ellucian.ethos.integration.client.EthosClientBuilder EthosClientBuilder }.
Declaration
public EthosMessagesClient(string apiKey, HttpClient client)
Parameters
| Type | Name | Description |
|---|---|---|
| System.String | apiKey | A valid API key from Ethos Integration. This is required to be a valid 36 character GUID string. If it is null, empty, or not in a valid GUID format, then an will be thrown.
|
| HttpClient | client | A HttpClient. If it is null/empty, then an |
Fields
cnType
The version to use for the Ethos Messages API.
Declaration
const string cnType = null
Field Value
| Type | Description |
|---|---|
| System.String |
Methods
ConsumeAsync(Nullable<Int32>, Nullable<Int64>)
Gets a list of messages from the subscription queue of the application. This will return the number of messages specified
by the limit parameter, if there are that many available. The messages will be returned in the format of a
change-notification.
The limit can be up to 1000, but the total size of the response payload from Ethos Integration is limited to 1 MB. If the size limit is reached, the number of messages returned will be less than the specified limit, even if there are more messages remaining in the queue.
The lastProcessedID parameter can be used to indicate the ID of the last message that was successfully processed. This parameter can be used to retrieve messages that have already been retrieved. The messages in the queue have sequential ID's, and the lastProcessedID parameter corresponds to the ID of a message in the queue.
Here is an example of how lastProcessedID can be used. If the application consuming the messages retrieves messages 1-10, but only successfully processes messages 1-5, it can set the lastProcessedID parameter to 5 in the next invocation.That will give the application messages 6-10 again.
When both the limit and lastProcessedID parameters are used together, they do not affect each other. The lastProcessedID gives a starting point on what message should be the first one returned. The limit is evaluated separately to see how many messages should be returned (starting with lastProcessedID + 1).
Declaration
public async Task<IEnumerable<ChangeNotification>> ConsumeAsync(int? limit = null, long? lastProcessedID = null)
Parameters
| Type | Name | Description |
|---|---|---|
| System.Nullable<System.Int32> | limit | The maximum number of messages to retrieve with a single request. This is required to be an integer between 1 and 1000, otherwise an InvalidOperationException will be thrown. |
| System.Nullable<System.Int64> | lastProcessedID | The ID of the last message that was successfully processed. |
Returns
| Type | Description |
|---|---|
| Task<IEnumerable<ChangeNotification>> | A list of messages in the change-notification format. This will return up to the given limit of messages if there are that many available in the queue and they all fit within the 1 MB payload limit. |
GetMessagesAsync(Nullable<Int32>, Nullable<Int64>)
Gets a list of messages from the subscription queue of the application. This will return the default number of messages, if available, from Ethos Integration in the format of a change-notification.
By default, each subsequent call to consume messages will remove the previously retrieved messages from the queue. If you need to get the same messages( or subset of them ) again, use the consume method that accepts a lastProcessedID parameter.
Declaration
async Task<IEnumerable<ChangeNotification>> GetMessagesAsync(int? limit, long? lastProcessedID)
Parameters
| Type | Name | Description |
|---|---|---|
| System.Nullable<System.Int32> | limit | The limit query parameter. |
| System.Nullable<System.Int64> | lastProcessedID | The lastProcessedID query parameter. |
Returns
| Type | Description |
|---|---|
| Task<IEnumerable<ChangeNotification>> | A list of change-notifications. |
GetNumAvailableMessagesAsync()
Gets the number of available messages in the subscription queue of the application. This will return 0 if the app has an empty queue or if the app has no subscriber queue.
Declaration
public async Task<int> GetNumAvailableMessagesAsync()
Returns
| Type | Description |
|---|---|
| Task<System.Int32> | The number of available messages in the application's queue. |