Show / Hide Table of Contents

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 }.

Inheritance
System.Object
EthosClient
EthosMessagesClient
Inherited Members
EthosClient.ApiKey
EthosClient.expirationMinutes
EthosClient.ExpirationMinutes
EthosClient.AutoRefresh
EthosClient.Token
EthosClient.Region
EthosClient.HttpProtocolClientBuilder
EthosClient.EthosResponseBuilder
EthosClient.ResponseHandlerAsync(HttpResponseMessage)
EthosClient.AttachHeaders(HttpClient, Dictionary<String, String>)
EthosClient.GetAccessTokenAsync()
EthosClient.GetNewTokenAsync()
EthosClient.GetHttpClient()
EthosClient.GetStringAsync(Dictionary<String, String>, String)
EthosClient.GetAsync(Dictionary<String, String>, String)
EthosClient.GetAsync(String)
EthosClient.HeadAsync(String)
EthosClient.PostAsync(Dictionary<String, String>, String, String)
EthosClient.PutAsync(Dictionary<String, String>, String, String)
EthosClient.DeleteAsync(Dictionary<String, String>, String)
EthosClient.AddAccessTokenAuthHeaderAsync(Dictionary<String, String>)
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

 ArgumentNullException
will be thrown.

HttpClient client

A HttpClient. If it is null/empty, then an will be thrown.

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.

In This Article
Back to top Generated by DocFX