com.sun.kvem.midp.io.j2se.wma.client
Class WMAClient

java.lang.Object
  |
  +--com.sun.kvem.midp.io.j2se.wma.client.WMAClient

public class WMAClient

extends java.lang.Object

Send and receive WMA Messages to other WMAClients via the WMA Server. A client can request a specific "phone number" from the WMA Server, or accept a server-assigned phone number.

A client can register as a gateway, which means that all WMA traffic addressed to unknown phone numbers will be routed to that client.

In order to use a client, you construct one and then call connect().

Before you call connect, the getters will return null information.

Nested Class Summary

static interface	WMAClient.MessageListener Register a MessageListener with a WMAClient to receive notification when a new message arrives.
static class	WMAClient.MessageListenerAdapter A convenience to easily create an anonymous MessageListener.

Field Summary

static int	CONNECT_TIMEOUT_MS How long the client waits for the server to respond to connect attempts.
static int	CONNECTION_ATTEMPTS How many retries before failing to connect to the server.
static java.lang.String	GATEWAY_PHONE_NUMBER The special phone number a client registering as a gateway should request.
static int	RECEIVE_ONLY Specify a client that can only receive messages, but not send them.
static int	SEND_AND_RECEIVE Specify a client that can send and receive messages.
static int	SEND_ONLY Specify a client that can only send messages, but not receive them.
static int[]	SMS_RESTRICTED_PORTS The ports on which SMS traffic may not be sent, as per the WMA specification.

Constructor Summary

WMAClient(java.lang.String phoneNumber, int clientType)
Construct a WMAClient with the requested phone number and client type.

Method Summary

void	connect() Connect to the WMA Server.
static boolean	ensureServerIsPresent()
int	getClientTrafficPort() Returns the port number this client uses for WMA traffic.
int	getClientType() Returns the type of this client: SEND_ONLY, RECEIVE_ONLY, or SEND_AND_RECEIVE.
int	getControlPort() Returns the port number on which the WMA Server is listening for client connections.
java.lang.String[]	getKnownReceivers() Returns a list of phone numbers that are registered with the WMA Server that can receive messages.
WMAClient.MessageListener	getMessageListener() Returns the MessageListener to be notified when messages are received.
java.lang.String	getPhoneNumber() Returns the phone number of this client.
int	getServerTrafficPort() Returns the port number the WMA Server is using for WMA traffic.
int	numberOfSegments(com.sun.kvem.midp.io.j2se.wma.Message message) Returns the number of segments that would be needed to send the specified Message.
static void	pingServer() Determine if the WMA Server is accessible.
com.sun.kvem.midp.io.j2se.wma.Message	receive() Receives and returns a whole WMA message.
com.sun.kvem.midp.io.j2se.wma.Message	receiveOneFragment() Receives and returns one message fragment.
void	send(com.sun.kvem.midp.io.j2se.wma.Message message) Send a WMA message.
void	setMessageListener(WMAClient.MessageListener notifyMe) Registers a listener to be notified when a new message arrived.
void	unregisterFromServer() Unregisters from the WMA Server.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CONNECT_TIMEOUT_MS

public static final int CONNECT_TIMEOUT_MS

How long the client waits for the server to respond to connect attempts. This is 1000 milliseconds.

See Also:

Constant Field Values

CONNECTION_ATTEMPTS

public static final int CONNECTION_ATTEMPTS

How many retries before failing to connect to the server. This is 5 attempts.

See Also:

Constant Field Values

GATEWAY_PHONE_NUMBER

public static final java.lang.String GATEWAY_PHONE_NUMBER

The special phone number a client registering as a gateway should request.

See Also:

Constant Field Values

RECEIVE_ONLY

public static final int RECEIVE_ONLY

Specify a client that can only receive messages, but not send them.

See Also:

Constant Field Values

SEND_AND_RECEIVE

public static final int SEND_AND_RECEIVE

Specify a client that can send and receive messages.

See Also:

Constant Field Values

SEND_ONLY

public static final int SEND_ONLY

Specify a client that can only send messages, but not receive them.

See Also:

Constant Field Values

SMS_RESTRICTED_PORTS

public static final int[] SMS_RESTRICTED_PORTS

The ports on which SMS traffic may not be sent, as per the WMA specification. These are:

2805 - WAP WTA secure connection-less session service

2923 - WAP WTA secure session service

2948 - WAP Push connectionless session service (client side)

2949 - WAP Push secure connectionless session service (client side)

5502 - Service Card reader

5503 - Internet access configuration reader

5508 - Dynamic Menu Control Protocol

5511 - Message Access Protocol

5512 - Simple Email Notification

9200 - WAP connectionless session service

9201 - WAP session service

9202 - WAP secure connectionless session service

9203 - WAP secure session service

9207 - WAP vCal Secure

49996 - SyncML OTA configuration

49999 - WAP OTA configuration

Constructor Detail

WMAClient

public WMAClient(java.lang.String phoneNumber,
                 int clientType)

Construct a WMAClient with the requested phone number and client type.

Parameters:

phoneNumber - the phone number requested for this client. Can be null, in which case the WMA Server will assign a phone number. If you are registering a gateway client, specify GATEWAY_PHONE_NUMBER.

clientType - the type of client this is. This should be one of SEND_ONLY, RECEIVE_ONLY, or SEND_AND_RECEIVE.

Throws:

java.lang.IllegalArgumentException - a GATEWAY_PHONE_NUMBER client cannot be SEND_ONLY

Method Detail

connect

public void connect()
             throws java.io.IOException,
                    PhoneNumberNotAvailableException

Connect to the WMA Server.

Throws:

java.io.IOException - there was a problem communicating with the WMA Server.

PhoneNumberNotAvailableException - the requested phone number is not available.

ensureServerIsPresent

public static boolean ensureServerIsPresent()

getClientTrafficPort

public int getClientTrafficPort()

Returns the port number this client uses for WMA traffic.

Returns:

the port number this client uses for WMA traffic.

getClientType

public int getClientType()

Returns the type of this client: SEND_ONLY, RECEIVE_ONLY, or SEND_AND_RECEIVE.

Returns:

the type of this client: SEND_ONLY, RECEIVE_ONLY, or SEND_AND_RECEIVE.

getControlPort

public int getControlPort()

Returns the port number on which the WMA Server is listening for client connections.

Returns:

the port number on which the WMA Server is listening for client connections.

getKnownReceivers

public java.lang.String[] getKnownReceivers()
                                     throws java.io.IOException

Returns a list of phone numbers that are registered with the WMA Server that can receive messages.

Returns:

a list of phone numbers that are registered with the WMA Server that can receive messages.

Throws:

java.io.IOException - there was a problem communicating with the WMA Server.

getMessageListener

public WMAClient.MessageListener getMessageListener()

Returns the MessageListener to be notified when messages are received.

Returns:

the MessageListener to be notified when messages are received.

getPhoneNumber

public java.lang.String getPhoneNumber()

Returns the phone number of this client.

Returns:

the phone number of this client.

getServerTrafficPort

public int getServerTrafficPort()

Returns the port number the WMA Server is using for WMA traffic.

Returns:

the port number the WMA Server is using for WMA traffic.

numberOfSegments

public int numberOfSegments(com.sun.kvem.midp.io.j2se.wma.Message message)

Returns the number of segments that would be needed to send the specified Message.

Note that this method does not actually send the message. It will only calculate the number of segments that would be required to send it.

Returns:

the number of segments required to send this Message.

pingServer

public static void pingServer()
                       throws java.io.IOException

Determine if the WMA Server is accessible.

Throws:

java.io.IOException - there was a problem communicating with the WMA Server.

receive

public com.sun.kvem.midp.io.j2se.wma.Message receive()
                                              throws java.io.IOException

Receives and returns a whole WMA message. This method blocks until a complete message has been received.

Returns:

the received Message

Throws:

java.lang.IllegalStateException - if the client is SEND_ONLY.

java.io.IOException - there was a problem communicating with the WMA Server.

receiveOneFragment

public com.sun.kvem.midp.io.j2se.wma.Message receiveOneFragment()
                                                         throws java.io.IOException

Receives and returns one message fragment. This method blocks until a fragment has been received.

Returns:

the received Message fragment.

Throws:

java.lang.IllegalStateException - if the client is SEND_ONLY.

java.io.IOException - there was a problem communicating with the WMA Server.

send

public void send(com.sun.kvem.midp.io.j2se.wma.Message message)
          throws java.io.IOException

Send a WMA message.

You can provide one of two kinds of Messages:

- a Message with only one segment (see Message.getNumSegments), in which case this function will split the message up into multiple fragments if necessary.

- a Message that is itself a segment already (see Message.getFragmentNum), in which case this function will send the message fragment as-is.

Parameters:

message - the Message or message fragment to send.

Throws:

java.lang.IllegalArgumentException - if the message address or content is invalid

java.lang.SecurityException - if the port is one of the SMS_RESTRICTED_PORTS.

java.lang.IllegalStateException - if the client is RECEIVE_ONLY.

java.io.IOException - there was a problem communicating with the WMA Server.

setMessageListener

public void setMessageListener(WMAClient.MessageListener notifyMe)

Registers a listener to be notified when a new message arrived.

The listener will only be notified once per received message, when its first segment arrives. It will be called on a separate thread.

Parameters:

notifyMe - the MessageListener to notify.

unregisterFromServer

public void unregisterFromServer()
                          throws java.io.IOException

Unregisters from the WMA Server. Call this when you no longer desire WMA messaging capabilities.

Throws:

java.io.IOException - there was a problem communicating with the WMA Server.