net.rim.device.api.io.messaging
Interface Destination

All Known Subinterfaces:
BlockingReceiverDestination, BlockingSenderDestination, FireAndForgetDestination, NonBlockingReceiverDestination, NonBlockingSenderDestination, ReceiverDestination, SenderDestination

public interface Destination

Encapsulates a target for messages. The target that a destination represents can either be remote or local from the perspective of the consumer of the Destination object. REMOTE destinations are Destination objects to which you want to send messages. Examples may include a web service, or a URI representing a queue for another application. A LOCAL destination is one that you want to receive messages from. Examples of LOCAL destinations include a Destination associated with a push URI (e.g. listens to pushes from an outside source), or a Reply-To queue from another application communication.

Exceptions are thrown when you try to use an unsupported operation on a destination, such as receive() on a REMOTE destination, or send() on a LOCAL destination).

Since:
BlackBerry API 6.0.0

Method Summary
 void destroy()
          Closes the destination.
 URI getUri()
          Returns the URI that this destination represents.
 void pause()
          Temporarily halts delivery of messages to this destination.
 void release()
          Releases a destination.
 void resume()
          Resumes delivery of messages to this destination.
 



Method Detail

destroy

void destroy()
Closes the destination. This method cancels all outstanding messages, discards all responses to those messages (if any), suspends delivery of all incoming messages, and blocks any future receipt of messages for this Destination. This method also destroys any persistable outbound and inbound queues. If Destination uses the Push API, this method will unregister associated push subscriptions. This method should be called only during the removal of an application.

Since:
BlackBerry API 6.0.0

release

void release()
Releases a destination. This method clears all references and resources required for a Destination when it is used in a currently running application. This method will not suspend delivery of incoming or outgoing messages, cancel any outgoing messages, or unregister any push subscriptions associated with the Destination This method should be used if an application using this Destination is closing, but will be used later (including Auto Start).

Since:
BlackBerry API 6.0.0

pause

void pause()
Temporarily halts delivery of messages to this destination. Any associated MessageListener objects will not receive any messages until the resume() method is called. If the Destination is already paused, then this operation will have no effect.

See Also:
Destination.resume()
Since:
BlackBerry API 6.0.0

resume

void resume()
Resumes delivery of messages to this destination. All queued messages will resume delivery to any associated MessageListener. If the Destination is not paused, then this operation has no effect.

See Also:
Destination.pause()
Since:
BlackBerry API 6.0.0

getUri

URI getUri()
Returns the URI that this destination represents.

Returns:
The URI that this destination represents.
Since:
BlackBerry API 6.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.