javax.wireless.messaging
Interface MessageConnection

All Superinterfaces:
javax.microedition.io.Connection

public interface MessageConnection
extends javax.microedition.io.Connection

The MessageConnection interface defines the basic functionality for sending and receiving messages. It contains methods for sending and receiving messages, factory methods to create a new Message object, and a method that calculates the number of segments of the underlying protocol that are needed to send a specified Message object.

This class is instantiated by a call to Connector.open(). An application SHOULD call close() when it is finished with the connection. An IOException is thrown when any method (except close), which is declared to throw an IOException, is called on the MessageConnection after the connection has been closed.

Messages are sent on a connection. A connection can be defined as server mode or client mode.

In a client mode connection, messages can only be sent. A client mode connection is created by passing a string identifying a destination address to the Connector.open() method. This method returns a MessageConnection object.

In a server mode connection, messages can be sent or received. A server mode connection is created by passing a string that identifies an end point (protocol dependent identifier, for example, a port number) on the local host to the Connector.open() method. If the requested end point identifier is already reserved, either by some system application or by another Java application, Connector.open() throws an IOException. Java applications can open MessageConnection s for any unreserved end point identifier, although security permissions might not allow it to send or receive messages using that end point identifier.

The scheme that identifies which protocol is used is specific to the given protocol. This interface does not assume any specific protocol and is intended for all wireless messaging protocols.

An application can have several MessageConnection instances open simultaneously; these connections can be both client and server mode.

The application can create a class that implements the MessageListener interface and register an instance of that class with the MessageConnection (s) to be notified of incoming messages. With this technique, a thread does not have to be blocked, waiting to receive messages.


Field Summary
static java.lang.String BINARY_MESSAGE
          Constant for a message type for binary messages (value = "binary").
static java.lang.String MULTIPART_MESSAGE
          Constant for a message type for multipart MIME messages (value = "multipart").
static java.lang.String TEXT_MESSAGE
          Constant for a message type for text messages (value = "text").
 
Method Summary
 Message newMessage(java.lang.String type)
          Constructs a new message object of a given type.
 Message newMessage(java.lang.String type, java.lang.String address)
          Constructs a new Message object of a given type and initializes it with the given destination address.
 int numberOfSegments(Message msg)
          Returns the number of segments in the underlying protocol that would be needed for sending the specified Message.
 Message receive()
          Receives a message.
 void send(Message msg)
          Sends a message.
 void setMessageListener(MessageListener l)
          Registers a MessageListener object that the platform can notify when a message has been received on this MessageConnection.
 
Methods inherited from interface javax.microedition.io.Connection
close
 

Field Detail

TEXT_MESSAGE

public static final java.lang.String TEXT_MESSAGE
Constant for a message type for text messages (value = "text"). If this constant is used for the type parameter in the newMessage() methods, then the newly created Message will be an instance implementing the TextMessage interface.

See Also:
Constant Field Values

BINARY_MESSAGE

public static final java.lang.String BINARY_MESSAGE
Constant for a message type for binary messages (value = "binary"). If this constant is used for the type parameter in the newMessage() methods, then the newly created Message will be an instance implementing the BinaryMessage interface.

See Also:
Constant Field Values

MULTIPART_MESSAGE

public static final java.lang.String MULTIPART_MESSAGE
Constant for a message type for multipart MIME messages (value = "multipart"). Using this constant as the type parameter in the newMessage() methods will cause the newly created Message to be an instance implementing the MultipartMessage interface.

Since:
WMA 2.0
See Also:
Constant Field Values
Method Detail

newMessage

public Message newMessage(java.lang.String type)
Constructs a new message object of a given type. When the type TEXT_MESSAGE is passed in, the created object implements the TextMessage interface. When type BINARY_MESSAGE constant is passed in, the created object implements the BinaryMessage interface. When type MULTIPART_MESSAGE is passed in, the created object implements the MultipartMessage interface. Adapter definitions for messaging protocols can define new constants and new subinterfaces for the Messages. The type strings are case-sensitive. The parameter is compared with the String.equals() method and does not need to be instance equivalent with the constants specified in this class.

For adapter definitions that are not defined within the JCP process, the strings used MUST begin with an inverted domain name controlled by the defining organization, as is used for Java package names. Strings that do not contain a full stop character "." are reserved for specifications done within the JCP process and MUST NOT be used by other organizations defining adapter specification.

When this method is called from a client mode connection, the newly created Message has the destination address set to the address identified when this Connection was created.

When this method is called from a server mode connection, the newly created Message does not have the destination address set. It must be set by the application before trying to send the message.

If the connection has been closed, this method still returns a Message instance.

Parameters:
type - the type of message to be created. There are constants for basic types defined in this interface.
Returns:
Message object for a given type of message
Throws:
java.lang.IllegalArgumentException - if the type parameters is not equal to the value of TEXT_MESSAGE, BINARY_MESSAGE, MULTIPART_MESSAGE or any other type value specified in a private or publicly standardized adapter specification that is supported by the implementation

newMessage

public Message newMessage(java.lang.String type,
                          java.lang.String address)
Constructs a new Message object of a given type and initializes it with the given destination address. The semantics related to the parameter type are the same as for the method signature with just the type parameter.

If the connection has been closed, this method still returns a Message instance.

Parameters:
type - the type of message to be created. There are constants for basic types defined in this interface.
address - destination address for the new message
Returns:
Message object for a given type of message
Throws:
java.lang.IllegalArgumentException - if the type parameters is not equal to the value of TEXT_MESSAGE, BINARY_MESSAGE,MULTIPART_MESSAGE or any other type value specified in a private or publicly standardized adapter specification that is supported by the implementation
See Also:
newMessage(String type)

send

public void send(Message msg)
          throws java.io.IOException,
                 java.io.InterruptedIOException
Sends a message.

Parameters:
msg - the message to be sent
Throws:
java.io.IOException - if the message could not be sent due to a network failure or if the connection is closed
java.lang.IllegalArgumentException - if the message is incomplete or contains invalid information. This exception is also thrown if the payload of the message exceeds the maximum length for the given messaging protocol. One specific case when the message is considered to contain invalid information is if the Message is not of the right type to be sent using this MessageConnection; the Message should be created using the newMessage() method of the same MessageConnection as will be used for sending it to ensure that it is of the right type.
java.io.InterruptedIOException - if a timeout occurs while either trying to send the message or if this Connection object is closed during this send operation
java.lang.NullPointerException - if the parameter is null
java.lang.SecurityException - if the application does not have permission to send the message
See Also:
receive()

receive

public Message receive()
                throws java.io.IOException,
                       java.io.InterruptedIOException
Receives a message.

If there are no Message s for this MessageConnection waiting, this method will block until either a message for this Connection is received or the MessageConnection is closed.

Returns:
a Message object representing the information in the received message
Throws:
java.io.IOException - if any of these situations occur:
  • there is an error while receiving a message
  • this method is called while the connection is closed
  • this method is called on a client mode MessageConnection
java.io.InterruptedIOException - if this MessageConnection object is closed during this receive method call
java.lang.SecurityException - if the application does not have permission to receive messages using the given port number
See Also:
send(Message)

setMessageListener

public void setMessageListener(MessageListener l)
                        throws java.io.IOException
Registers a MessageListener object that the platform can notify when a message has been received on this MessageConnection.

If there are incoming messages in the queue of this MessageConnection that have not been retrieved by the application prior to calling this method, the newly registered listener object will be notified immediately once for each such incoming message in the queue.

There can be at most one listener object registered for a MessageConnection object at any given point in time. Setting a new listener will de-register any previously set listener.

Passing null as the parameter will de-register any currently registered listener.

Parameters:
l - MessageListener object to be registered. If null, any currently registered listener will be de-registered and will not receive notifications.
Throws:
java.lang.SecurityException - if the application does not have permission to receive messages using the given port number
java.io.IOException - if the connection has been closed, or if an attempt is made to register a listener on a client connection

numberOfSegments

public int numberOfSegments(Message msg)
Returns the number of segments in the underlying protocol that would be needed for sending the specified Message.

Note that this method does not actually send the message. It will only calculate the number of protocol segments needed for sending the message.

This method will calculate the number of segments needed when this message is split into the protocol segments using the appropriate features of the underlying protocol. This method does not take into account possible limitations of the implementation that may limit the number of segments that can be sent using this feature. These limitations are protocol-specific and are documented with the adapter definition for that protocol.

If the connection has been closed, this method returns a count of the message segments that would be sent for the provided Message.

Parameters:
msg - the message to be used for the calculation
Returns:
number of protocol segments needed for sending the message. Returns 0 if the Message object cannot be sent using the underlying protocol.


Copyright (C) 2004 Siemens AG, Germany. All rights reserved. Use is subject to license terms.