JSR 120: Wireless Messaging API

The most famous mobile data application around the world is Short Messaging Service (SMS). Nobody had expected that it will become so popular when it was introduced. In fact when our company talks to clients for mobile based data applications they generally ask for SMS related applications.

MIDP 1.0 did not contain any facility for sending or receiving SMS. This was a major drawback. In fact I remember that once a client did not give our company a contract for J2ME applications because MIDP 1.0 did not support SMS. Sensing these problems that a lot of companies were encountering JSR 120 – Wireless Messagin API was launched. It has brought the power of sending and receiving SMS to the java applications. It is a very simple but powerfull API. The only drawback which I have encountered while working with this API is that while you can send SMS to anybody you can not receive SMS in the applications from ordinary mobile phones. This problem is due to the fact that to receive SMS the application has to book a port. Since normal mobiles can not add specific port number in the receiver’s address there is no way receiving the SMS from a normal mobile phone to a phone containing a J2ME based SMS application. The SMS always goes to the phone inbox instead of the application. Also JSR 120 does not support application activation on receiving an SMS for the application. The SMS is received only when the application is active.

Inspite of these short comings JSR 120 is excellent from the point of sending SMS. It also contains the facility for sending binary SMS. This is a very usefull feature and can even be used for secure communication by writing a class to encrypt the SMS and then send it. The receiver will decode the SMS and show the message to the user or act according to the application logic.

 

javax.microedition.io

 

public class Connector

What is it?

Connector is a factory class for creating new Connection objects.

 

o    Field

·         public static final int READ

This field stands for the access mode READ.

 

·         public static final int READ_WRITE

This field stands for the access mode READ_WRITE.

 

·         public static final int WRITE

This field stands for the access mode WRITE.

 

o    Method   

·         public static javax.microedition.io.Connection open(java.lang.String name) throws IOException

This method returns a new Connection object. The only parameter of this method contains the URL for the connection.

 

·         public static javax.microedition.io.Connection open(java.lang.String name, int mode) throws IOException

This method returns a new Connection object. The first parameter of this method contains the URL for the connection. The other one contains the access mode.

 

·         public static javax.microedition.io.Connection open(java.lang.String name, int mode,boolean timeouts) throws IOException

This method returns a new Connection object. The first parameter of this method contains the URL for the connection. The second one contains the access mode. The thirg contains a flag that tells that the caller wants timeout actions.

 

·         public static java.io.DataInputStream openDataInputStream(java.lang.String name) throws IOException

This method returns a DataInputStream.

 

·         public static java.io.DataOutputStream openDataOutputStream(java.lang.String name) throws IOException

This method returns a DataOutputStream.

 

·         public static java.io.InputStream openInputStream(java.lang.String name) throws IOException

This method returns an InputStream.

 

·         publicstaticjava.io.OutputStreamopenOutputStream(java.lang.String name)

This method returns an OutputStream.

 

public interface BinaryMessage extends Message

What is it?

BinaryMessage is an interface that represents a binary message. BinaryMessage contains methods to get and set the binary data payload.

 

o    Method

 

·         public byte[] getPayloadData()

This method returns the payload data of this message. If the data has not been set it returns null.

 

·         public setPayloadData(byte[] data)

This method is used for setting the payload data. The payload data is in form of a byte array.

 

·         public interface Message

What is it?

Message is the base interface for interfaces that represent various types of messages. This interface defines the common functionality between various messages. The whole approach of ‘Wireless Messaging API’ is that the message can communicated independent of the network type be it GSM or CDMA.

 

o    Methods

 

·         public java.lang.String getAddress()

This method returns the address of this message. In case the address is not set it returns null.

 

 

·         public java.util.Date getTimestamp()

This method returns the date object indicating when this message has been sent.

 

·         public void setAddress(java.lang.String addr)

This message sets the address associated with this message. Setting null is a valid value.

 

public interface MessageConnection extends javax.microedition.io.Connection

What is it?

MessageConnection interface helps in sending and receiving the messages. The MessageConnection interface contains the following functionality:

 

·   Methods for sending and receiving the messages

·   Methods for creating new messages.

·   Method to calculate the number SMS required for sending the message.

 

o    Fields

 

·         public static final java.lang.String BINARY_MESSAGE

This field is a constant for message type binary messages.

 

·         public static final java.lang.String TEXT_MESSAGE

This field is a constant for message type text messages.

 

o    Methods

·         public javax.wireless.messaging.Message newMessage(java.lang.String type)

This method returns a Message object for a given type of message.

 

·         public javax.wireless.messaging.Message newMessage(javlang.String type, java.lang.String address)

This method returns a Message object for a given type of message with a particular destination address.

 

·         public int numberOfSegments(javax.wireless.messaging.Message msg)

This method returns number of protocol segments needed for sending the message. This method will return 0 if the Message object cannot be sent using the underlying protocol.

 

·         public javax.wireless.messaging.Message receive() throws IOException, InterruptedIOException

This method helps in receiving a message. This method will block until either the message is received or the MessageConnection is closed.       

 

·         public void send(javax.wireless.messaging.Message msg) throws IOException, InterruptedIOException

This method helps in sending a message.

 

·         Public void setMessageListener(javax.wireless.messaging.MessageListener l)throws IOException

This method registers a MessageListener object to which the platform can notify that a message has been received on this MessageConnection.

 

public interface MessageListener

What is it?

This interface provides a mechanism for the application to be notified of incoming messages when they arrive.

 

o    Methods

 

·         public void notifyIncomingMessage(javax.wireless.messaging.MessageConnection conn)

This method is called by the platform when an incoming message arrives to a MessageConnection for which the application has registered this listener object.

 

public interface TextMessage extends Message

What is it?

TextMessage is an interface that represents a text message. This interface contains methods to get and set the text payload.

o    Methods

 

·         public java.lang.String getPayloadText()

This method returns the text payload of this message. It returns null if the payload for the message is not set.

 

·         public void setPayloadText(java.lang.String data)

This method sets the payload text data of this message. The payload data may be null.

 

 

// To rectify the diagram

Diagram           :           Wireless Messaging API (JSR 205)

 

JSR 205 : Wireless Messaging API 2.0

 

Now we will be discussing the JSR 205. The recent changes in the technology have led to the need of supporting multipart messages. With the introduction of Multimedia Messaging (MMS) the need was felt for APIs which could help a J2ME application send a multimedia message. With this in mind the JSR 205 was released. Since the JSR 205 is using JSR 120 as its base we will be only discussing the new APIs. The classes and interfaces contained in JSR 120 have not been discussed.

 

javax.wireless.messaging.MessagePart

 

public class MessagePart

What is it?

The MessagePart class’s instances can be added to a MultipartMessage. MessagePart consists of the following:

·   Content element

·   MIME type

·   Content-id.

 

The content contained in a MessagePart can be of any type. It is also possible to specify the content location and the encoding scheme in a MessagePart.

 

o    Constructors

• public MessagePart(byte[] contents, int offset, int length, java.lang.String mimeType, java.lang.String contentId, java.lang.String contentLocation, java.lang.String enc) throws SizeExceededException

This constructor constructs a MessagePart object from a subset of the byte array given in the parameter. This constructor is suitable for small messages only.

·         public MessagePart (byte [] contents, java.lang.String mimeType, java.lang.String contentId, java.lang.String contentLocation, java.lang.String enc) throws SizeExceededException

This constructor constructs a MessagePart object from the given byte array. This constructor is useful only if the data size is small i.e. roughly less than 10Kb.

·         public MessagePart(java.io.InputStream is, java.lang.String mimeType, java.lang.String contentId, java.lang.String contentLocation, java.lang.String enc) throws IOException, SizeExceededException

This constructor constructs a MessagePart object from an InputStream. The contents of the MessagePart are loaded from the InputStream during the constructor call. The contents are loaded until the end of stream is reached. This method is useful even for bigger data payloads.

 

o    Methods

• public byte[] getContent()

             This method returns MessagePart data as byte array.

·         public java.io.InputStream getContentAsStream()

This method returns an InputStream that can be used for reading the contents of this MessagePart.

·         public java.lang.String getContentID()

This method returns the value of content-id as a String. Otherwise it returns null if the content-id is not set. This scenario can happen if the message was sent from a non JSR 205 compliant device.

·         public java.lang.String getContentLocation()

             This method returns content location.

·         public java.lang.String getEncoding()

This method returns encoding of the MessagePart content otherwise it returns null if the encoding scheme of the MessagePart cannot be determined.

·         public int getLength()

This method returns content size of this MessagePart. It returns 0 if the MessagePart is empty. The content size is returned in bytes.

·         public java.lang.String getMIMEType()

This method returns MIME type of the MessagePart.

 

public interface MultipartMessage extends Message

What is it?

MultipartMessage is an interface representing a multipart message. It contains methods to add and get MessageParts. MultipartMessage also allows specifying the subject of the message. It also offers methods to get and set special header fields of the message.

 

o    Methods

·         public boolean addAddress(java.lang.String type, java.lang.String address)

This method allows us to add the following types of addresses:

·   “to”

·   “cc”

·   “bcc”

 

The address types are defined in form of above mentioned strings. The second parameter takes in the address. This method returns true if it was possible to add the address otherwise it returns false.

·         public void addMessagePart(javax.wireless.messaging.MessagePart part) throws SizeExceededException

This method attaches a MessagePart to the multipart message.

·         public java.lang.String getAddress()

This method returns the “from” or “to” address of this message. It may also return null if the address that is expected as a result of the method is not set.

·         public java.lang.String[] getAddresses(java.lang.String type)

This method returns the addresses as a String array or null if the address of the specified type is not present.

·         public java.lang.String getHeader(java.lang.String headerField)

This method returns the content of the specified header field as a String or null if the specified header field is not present.

·         public javax.wireless.messaging.MessagePart getMessagePart(java.lang.String contentID)

This method returns MessagePart that matches the provided content-id or null if there is no MessagePart in this message with the provided content-id

·         public javax.wireless.messaging.MessagePart[] getMessageParts()

This method returns array of MessageParts or null if no MessageParts are available.

·         public java.lang.String getStartContentId()

This method returns the content-id of the start MessagePart or null if the start MessagePart is not set.

·         public java.lang.String getSubject()

This method returns the message subject as a String or null if this value is not present.

·         public boolean removeAddress(java.lang.String type, java.lang.String address)

This method returns true if it was possible to delete the address else it returns false.

·         public void removeAddresses()

This method removes all addresses of types “to”, “cc”, and “bcc” from the multipart message.

·         public void removeAddresses(java.lang.String type)

This method removes all addresses of the specified type from the multipart message.

·         public boolean removeMessagePart(javax.wireless.messaging.MessagePart part)

This method returns true if it was possible to remove the MessagePart otherwise it returns false.

·         public boolean removeMessagePartId(java.lang.String contentID)

This method returns true if it was possible to remove the MessagePart with the given contented otherwise it returns false.

·         public boolean removeMessagePartLocation(java.lang.String contentLocation)

This method returns true if it was possible to remove the MessagePart at the specified content location otherwise it will return false.

·         public void setAddress(java.lang.String addr)

This method sets the “to” address associated with this message. The address parameter may be set to null.

·         public void setHeader(java.lang.String headerField, java.lang.String headerValue)

This method sets the specific header of the multipart message. The header value that is being set can be null.

·         public void setStartContentId(java.lang.String contentId)

This method sets the Content-ID of the start MessagePart.

·         public void setSubject(java.lang.String subject)

This method sets the subject of the multipart message. This subject can be null.

 

public class SizeExceededException

What is it?

This exception inidicates that an operation is not executable due to insufficient system resources.

o    Constructor

·         public SizeExceededException(java.lang.String reason)

This constructor constructs a new exception.