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

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.
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.
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.
void	registerAccessPoint(AccessPoint accessPoint) Register an access point for receiving messages.
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.
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

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.

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.

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.

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.

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.

getVersion

java.lang.String getVersion()

Get the version number of this Messaging Client API.

Returns:

the version number of this client API.

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:

a list 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.

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)

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)

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.

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.

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)

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)