oracle.sdp.messaging
Interface MessagingClient

All Superinterfaces:

Serializable

All Known Subinterfaces:

MessagingEJBClient

public interface MessagingClient
extends Serializable

Base interface of all SDP Messaging clients: EJB Client, Web Service Client, etc.

Since:

11.0.0

Field Summary

static java.lang.String

VERSION_NUMBER The Messaging Client API version number.

Method Summary

void	acknowledge() Acknowledge all outstanding messages that have been received using any of the receive methods in this class.
boolean	cancel(java.lang.String messageId) Cancel a message previously sent.
AccessPoint[]	getAccessPoints() Get a list of all access points currently registered by this application.
MessageFilter[]	getMessageFilters() Get the set of currently registered message filters for this application.
Iterator<java.lang.String>	getMessageIDs(MessageQuery query) Get the ids of all sent messages that fit the specified search criteria.
Listener	getMessageListener() Get a reference to the current default message listener, if any.
Status[]	getStatus(java.lang.String messageId) Get the up-to-date statuses of all recipients of a sent message.
Status[]	getStatus(java.lang.String messageId, Address[] addresses) Get all sending and failover statuses up to date of a set of recipients.
Listener	getStatusListener() Get a reference to the current default status listener, if any.
java.lang.String[]	getSupportedChannels() Get a list of the current delivery channels supported by the Messaging Server that this client is connected to.
DeliveryType[]	getSupportedDeliveryTypes() Get a list of the current delivery types supported by the Messaging Server that this client is connected to.
java.lang.String	getVersion() Get the version number of this Messaging Client API.
Message[]	receive() Synchronously receive messages.
Message[]	receive(AccessPoint accessPoint) Perform a synchronous receive operation for a particular AccessPoint registered by this client.
Message[]	receiveLimited(AccessPoint accessPoint, int maxNrOfReceivedMessages) Perform a synchronous receive operation for a particular AccessPoint registered by this client.
Message[]	receiveLimited(int maxNrOfReceivedMessages) Synchronously receive a limited number of messages.
void	registerAccessPoint(AccessPoint accessPoint) Register an access point for receiving messages.
void	registerAccessPoint(AccessPoint accessPoint, Listener listener, Serializable correlator) Register an access point, specifying a MessageListener callback object.
void	registerAccessPoints(AccessPoint[] accessPoints) Register a set of access points.
void	registerMessageFilter(MessageFilter filter) Register a message filter.
void	registerMessageFilters(MessageFilter[] filters) Register a set of message filters.
java.lang.String	replace(java.lang.String messageId, Message message) Replace a message previously submitted to the gateway for sending with a new Message.
java.lang.String	send(Message message) Send a message.
java.lang.String	send(Message message, Listener listener, Serializable correlator) Send a message, specifying a StatusListener callback object.
void	setMessageListener(Listener listener) Set a default message listener.
void	setStatusListener(Listener listener) Set a default status listener.
void	unregisterAccessPoint(AccessPoint accessPoint) Unregister an access point.
void	unregisterAccessPoints(AccessPoint[] accessPoints) Unregister a set of access points.
void	unregisterMessageFilter(MessageFilter filter) Remove a message filter from the current filter chain.
void	unregisterMessageFilters(MessageFilter[] filters) Remove a set of message filters from the current filter chain.

Field Detail

VERSION_NUMBER

static final java.lang.String VERSION_NUMBER

The Messaging Client API version number.

See Also:

Constant Field Values

Method Detail

getVersion

java.lang.String getVersion()

Get the version number of this Messaging Client API.

Returns:

the version number of this client API.

send

java.lang.String send(Message message)
                      throws MessagingException

Send a message.

Parameters:

message - the message to be delivered.

Returns:

a single message identifier will be returned after server accepts the request.

Throws:

MessagingException - if the message cannot be sent.

receive

Message[] receive()
                  throws MessagingException,
                         NotSupportedException

Synchronously receive messages. This is a convenient polling method for light-weight clients that do not want the configuration overhead associated with receiving messages asynchronously. This method returns a list of messages that are immediately available in the application inbound queue.

It performs a non-blocking call, so if no message is currently available, the method returns null.

Note: A single invocation does not guarantee retrieval of all available messages. You must poll to ensure receiving all available messages.

Returns:

an array of messages received, or null.

Throws:

MessagingException - if there was an error while attempting to receive a message.

NotSupportedException - if this operation is not supported by this implementation.

receiveLimited

Message[] receiveLimited(int maxNrOfReceivedMessages)
                         throws MessagingException,
                                NotSupportedException

Synchronously receive a limited number of messages. See receive().

Parameters:

maxNrOfReceivedMessages - max number of messages that will be returned. If < 1 or > internal max value, it is set to the internal max value.

Returns:

an array of messages received, or null.

Throws:

MessagingException - if there was an error while attempting to receive a message.

NotSupportedException - if this operation is not supported by this implementation.

cancel

boolean cancel(java.lang.String messageId)
               throws MessagingException,
                      NoPermissionException

Cancel a message previously sent.

Parameters:

messageId - message identifier of existing Message to be cancelled.

Returns:

true, if the operation is successful. false, if the message cannot be cancelled.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the message cannot be cancelled.

replace

java.lang.String replace(java.lang.String messageId,
                         Message message)
                         throws MessagingException,
                                NoPermissionException

Replace a message previously submitted to the gateway for sending with a new Message.

Parameters:

messageId - message identifier of existing Message to be replaced.

message - the new message.

Returns:

a new message identifier will be returned after server accepts the request.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the message cannot be found or replaced.

getMessageIDs

Iterator<java.lang.String> getMessageIDs(MessageQuery query)
                                         throws MessagingException

Get the ids of all sent messages that fit the specified search criteria.

Parameters:

query - the message query.

Returns:

an iterator of the id strings for all sent messages that fit the search criteria.

Throws:

MessagingException

getStatus

Status[] getStatus(java.lang.String messageId)
                   throws MessagingException,
                          NoPermissionException

Get the up-to-date statuses of all recipients of a sent message. Statuses for each recipient address will be set by the server.

Parameters:

messageId - the message identifier of a previously sent Message.

Returns:

a list of statuses, one for each recipient of the message.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the statuses cannot be retrieved.

getStatus

Status[] getStatus(java.lang.String messageId,
                   Address[] addresses)
                   throws MessagingException,
                          NoPermissionException

Get all sending and failover statuses up to date of a set of recipients. Statuses of each recipient address will be set by the server. If the query is for a "group" recipient, the statuses returned will be of the expanded users of the group.

Parameters:

messageId - the message identifier of a previously sent Message.

addresses - the set of recipient addresses whose statuses are requested.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the statuses cannot be retrieved.

registerAccessPoint

void registerAccessPoint(AccessPoint accessPoint)
                         throws MessagingException,
                                NoPermissionException

Register an access point for receiving messages.

For example:

• To register an SMS access point for the number 9000:
  AccessPoint accessPointSingleAddress = AccessPointFactory.createAccessPoint(AccessPoint.AccessPointType.SINGLE_ADDRESS, DeliveryType.SMS, "9000");
messagingClient.registerAccessPoint(accessPointSingleAddress);
• To register SMS access points in the number range 9000 to 9999:
  AccessPoint accessPointRangeAddress = AccessPointFactory.createAccessPoint(AccessPoint.AccessPointType.NUMBER_RANGE, DeliveryType.SMS,"9000,9999");
messagingClient.registerAccessPoint(accessPointRangeAddress);

Parameters:

accessPoint - the access point to register.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation, for example if the access point is already registered by another application. In the case of a Number Range access point, registration is "all or nothing" - if any of the addresses in the range is unavailable, none of the addresses will be registered.

MessagingException - if the access point cannot be registered.

registerAccessPoints

void registerAccessPoints(AccessPoint[] accessPoints)
                          throws MessagingException,
                                 NoPermissionException

Register a set of access points.

Parameters:

accessPoints - the set of access points to register.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the access points cannot be registered.

See Also:

registerAccessPoint(AccessPoint)

unregisterAccessPoint

void unregisterAccessPoint(AccessPoint accessPoint)
                           throws MessagingException,
                                  NoPermissionException

Unregister an access point.

Parameters:

accessPoint - the access point to unregister.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the access point cannot be unregistered.

unregisterAccessPoints

void unregisterAccessPoints(AccessPoint[] accessPoints)
                            throws MessagingException,
                                   NoPermissionException

Unregister a set of access points.

Parameters:

accessPoints - the set of access points to unregister.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the access points cannot be unregistered.

See Also:

unregisterAccessPoint(AccessPoint)

getAccessPoints

AccessPoint[] getAccessPoints()
                              throws MessagingException,
                                     NoPermissionException

Get a list of all access points currently registered by this application.

Returns:

an array of all access points currently registered by this application.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the access points cannot be retrieved.

registerMessageFilter

void registerMessageFilter(MessageFilter filter)
                           throws MessagingException,
                                  NoPermissionException

Register a message filter. The filter is added to the end of the current filter chain for the application. When a message is received, it is passed throug the filter chain in order; if the message matches a filter's criterion, the filter's action is taken immediately. If no filters match the message, the default action is to accept the message and deliver it to the application.

For example:

• To reject messages with subject="spam":
  MessageFilter subjectFilter = MessageFilterFactory.createMessageFilter("spam", MessageFilter.FieldType.SUBJECT, null, MessageFilter.Action.REJECT);
messagingClient.registerMessageFilter(subjectFilter);
• To reject messages from email address "spammer@foo.com":
  MessageFilter senderFilter = MessageFilterFactory.createBlacklistFilter("spammer@foo.com");
messagingClient.registerMessageFilter(senderFilter);

Parameters:

filter - the filter to register. *

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the message filter cannot be registered.

registerMessageFilters

void registerMessageFilters(MessageFilter[] filters)
                            throws MessagingException,
                                   NoPermissionException

Register a set of message filters.

Parameters:

filters - the filters to register.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the message filters cannot be registered.

See Also:

registerMessageFilter(MessageFilter)

unregisterMessageFilter

void unregisterMessageFilter(MessageFilter filter)
                             throws MessagingException,
                                    NoPermissionException

Remove a message filter from the current filter chain. The given filter must match the existing one in the chain exactly -- same criteria and action.

Parameters:

filter - the filter to unregister.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the message filter cannot be unregistered.

unregisterMessageFilters

void unregisterMessageFilters(MessageFilter[] filters)
                              throws MessagingException,
                                     NoPermissionException

Remove a set of message filters from the current filter chain.

Parameters:

filters - the filters to unregister.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the message filters cannot be unregistered.

See Also:

unregisterMessageFilter(MessageFilter)

getMessageFilters

MessageFilter[] getMessageFilters()
                                  throws MessagingException,
                                         NoPermissionException

Get the set of currently registered message filters for this application.

Returns:

an array of the current message filters, in the order that they are applied to an incoming message.

Throws:

NoPermissionException - if the client has insufficient permissions to perform this operation.

MessagingException - if the message filters cannot be retrieved.

getSupportedDeliveryTypes

DeliveryType[] getSupportedDeliveryTypes()
                                         throws MessagingException

Get a list of the current delivery types supported by the Messaging Server that this client is connected to.

Returns:

a list of the supported delivery types.

Throws:

MessagingException - if there is an error while invoking this operation.

getSupportedChannels

java.lang.String[] getSupportedChannels()
                                        throws MessagingException

Get a list of the current delivery channels supported by the Messaging Server that this client is connected to.

Returns:

a list of the supported delivery channels.

Throws:

MessagingException - if there is an error while invoking this operation.

send

java.lang.String send(Message message,
                      Listener listener,
                      Serializable correlator)
                      throws MessagingException

Send a message, specifying a StatusListener callback object. The listener will be invoked with any delivery status notifications that result during the sending of this message.

Parameters:

message -

listener -

correlator - Any serializable object. If provided, this object will be passed back to the onStatus callback method when a status notification is received.

Returns:

Throws:

MessagingException

Since:

11.1.1.3.0

receive

Message[] receive(AccessPoint accessPoint)
                  throws MessagingException

Perform a synchronous receive operation for a particular AccessPoint registered by this client. This receive call will return 0 or more inbound messages that were matched to the specified AccessPoint.

Parameters:

accessPoint -

Returns:

Throws:

MessagingException

Since:

11.1.1.3.0

receiveLimited

Message[] receiveLimited(AccessPoint accessPoint,
                         int maxNrOfReceivedMessages)
                         throws MessagingException

Perform a synchronous receive operation for a particular AccessPoint registered by this client. This receive call will return 0 or up to maxNrOfReceivedMessages inbound messages that were matched to the specified AccessPoint.

Parameters:

accessPoint - the accessPoint to receive messages for.

maxNrOfReceivedMessages - max number of messages that will be returned. If < 1 or > internal max value, it is set to the internal max value.

Returns:

Throws:

MessagingException

Since:

11.1.1.6.0

acknowledge

void acknowledge()
                 throws MessagingException

Acknowledge all outstanding messages that have been received using any of the receive methods in this class. The acknowledged messages will be marked as successfully processed and will not be re-delivered in the event of a server failure or other unexpected event.

Throws:

MessagingException

Since:

11.1.1.3.0

registerAccessPoint

void registerAccessPoint(AccessPoint accessPoint,
                         Listener listener,
                         Serializable correlator)
                         throws MessagingException

Register an access point, specifying a MessageListener callback object. The listener will be invoked for any inbound messages that resolve to the specified access point.

Parameters:

accessPoint -

listener -

correlator - Any serializable object. If provided, his object will be passed back to the onMessage callback method when a message is received.

Throws:

MessagingException

Since:

11.1.1.3.0

setMessageListener

void setMessageListener(Listener listener)
                        throws MessagingException

Set a default message listener. This listener will be invoked for any messages routed to AccessPoints owned by this client application that don't have an associated listener. To remove the default listener, call this method with a null argument.

Parameters:

listener -

Throws:

MessagingException

Since:

11.1.1.3.0

getMessageListener

Listener getMessageListener()
                            throws MessagingException

Get a reference to the current default message listener, if any.

Returns:

Throws:

MessagingException

Since:

11.1.1.3.0

setStatusListener

void setStatusListener(Listener listener)
                       throws MessagingException

Set a default status listener. This listener will be invoked for any delivery statuses for messages sent by this client application that don't have an assoicated listener. To remove a defautl listener, call this method with a null argument.

Parameters:

listener -

Throws:

MessagingException

Since:

11.1.1.3.0

getStatusListener

Listener getStatusListener()
                           throws MessagingException

Get a reference to the current default status listener, if any.

Returns:

Throws:

MessagingException

Since:

11.1.1.3.0