Package com.ellucian.ethos.integration.client.messages

Class EthosMessagesClient

java.lang.Object

com.ellucian.ethos.integration.client.EthosClient

com.ellucian.ethos.integration.client.messages.EthosMessagesClient

public class EthosMessagesClient
extends EthosClient

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

Since:

0.0.1

Field Summary

Fields inherited from class com.ellucian.ethos.integration.client.EthosClient

ethosResponseBuilder, httpProtocolClientBuilder, responseHandler, token

Constructor Summary

Constructors

Constructor	Description
EthosMessagesClient(String apiKey, Integer connectionTimeout, Integer connectionRequestTimeout, Integer socketTimeout)	Creates an EthosMessagesClient using the given API key.

Method Summary

Modifier and Type	Method	Description
List<ChangeNotification>	consume()	Gets a list of messages from the subscription queue of the application.
List<ChangeNotification>	consume(int limit, int lastProcessedID)	Gets a list of messages from the subscription queue of the application.
List<ChangeNotification>	consumeFromId(int lastProcessedID)	Gets a list of messages from the subscription queue of the application, starting after the given ID.
List<ChangeNotification>	consumeWithLimit(int limit)	Gets a list of messages from the subscription queue of the application.
int	getNumAvailableMessages()	Gets the number of available messages in the subscription queue of the application.

Methods inherited from class com.ellucian.ethos.integration.client.EthosClient

delete, get, get, getAccessToken, getAutoRefresh, getExpirationMinutes, getHttpClient, getRegion, head, post, put, setAutoRefresh, setExpirationMinutes, setRegion, submitRequest

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EthosMessagesClient

public EthosMessagesClient(String apiKey,
                           Integer connectionTimeout,
                           Integer connectionRequestTimeout,
                           Integer socketTimeout)

Creates an EthosMessagesClient using the given API key. Note that the preferred way to get an instance of this class is through the EthosClientBuilder.

Parameters:

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 IllegalArgumentException will be thrown.

connectionTimeout - The timeout in seconds for a connection to be established.

connectionRequestTimeout - The timeout in seconds when requesting a connection from the Apache connection manager.

socketTimeout - The timeout in seconds when waiting for data between consecutive data packets.

Method Detail

consume

public List<ChangeNotification> consume()
                                 throws IOException

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.

Returns:

A list of messages in the change-notification format.

Throws:

IOException - if there is an error making the HTTP request

consumeWithLimit

public List<ChangeNotification> consumeWithLimit(int limit)
                                          throws IOException

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.

Parameters:

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 IllegalArgumentException will be thrown.

Returns:

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.

Throws:

IOException - if there is an error making the HTTP request

consumeFromId

public List<ChangeNotification> consumeFromId(int lastProcessedID)
                                       throws IOException

Gets a list of messages from the subscription queue of the application, starting after the given ID. This will return the default number of messages, if available, from Ethos Integration in the format of a change-notification.

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.

Parameters:

lastProcessedID - The ID of the last message that was successfully processed.

Returns:

A list of messages in the change-notification format.

Throws:

IOException - if there is an error making the HTTP request

consume

public List<ChangeNotification> consume(int limit,
                                        int lastProcessedID)
                                 throws IOException

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

Parameters:

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 IllegalArgumentException will be thrown.

lastProcessedID - The ID of the last message that was successfully processed.

Returns:

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.

Throws:

IOException - if there is an error making the HTTP request

getNumAvailableMessages

public int getNumAvailableMessages()
                            throws IOException

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.

Returns:

The number of available messages in the application's queue

Throws:

IOException - if there is an error making the HTTP request