j2meClient.nMIDlet Class Reference

Nirvana j2me Client API Package, incorporating pub / sub & message queues This class subclasses MIDlet becoming the new base class for MIDP and IMP applications that wish to use Nirvana. More...

Inheritance diagram for j2meClient.nMIDlet:

j2meP2PClient.nP2PMIDlet

Public Member Functions

void delConnection (String channelName, String connectionId)
 This method is called asynchronously when a subscription is removed from the nirvana channel.
void disconnected (nObject anSession)
 This method is called asynchronously when a session is disconnected.
abstract void go (nObject consumeevent)
 Adds an async listener for this queue.
void handleException (Exception exception)
 This method is called asynchronously when an exception occurs during an asynchronous operation.
void newConnection (String channelName, String connectionId, String[] subject, String filter, String protocol, String subscriberName)
 This method is called asynchronously when a new subscription is registered to a nirvana channel.
void reconnected (nObject anSession)
 Registers the specified nEventListener as a named subscriber to this channel.
boolean tryAgain (nObject anSession)
 This method is called asynchronously between a session being disconnected and a reconnection attempt.

Static Public Member Functions

static void addAsyncExceptionListener (nObject session, nMIDlet listener) throws Exception
 Adds a new asynchronous exception listener, which will be notified when an exception occurs while performing an asynchronous operation.
static void addChannelConnectionListener (nObject channel, nMIDlet listener) throws Exception
 Adds a channel connection listener, which will be notified when a new subscriber is added to the channel or an existing subscriber unsubscribes from the channel.
static void addQueueListener (nObject queue, nMIDlet listener, String selector) throws Exception
 Adds an asynchronous channel event listener, which will be notified when events are published on the channel via a callback in the go method.
static void addSubscriber (nObject channel, nMIDlet listener, nObject namedobject, String selector, boolean AutoAck) throws Exception
 Adds an asynchronous channel event listener, which will be notified when events are published on the channel via a callback in the go method.
static void addSubscriber (nObject channel, nMIDlet listener, String selector, long starteid) throws Exception
 Adds an asynchronous channel event listener, which will be notified when events are published on the channel via a callback in the go method.
static nObject getChannelSession (nObject channelorqueue) throws Exception
 Registers the specified nEventListener as a subscriber to this channel.
static String getConnectionPropertiesSuffix (String connectorURL, byte connectivityoption)
 endif
static byte getConnectivityOption ()
 Returns the currently configured connectivity option flag (INTERNET_APN_OPTION_FLAG or BES_OPTION_FLAG) [Blackberry only].
static int getMaxBufferSize (nObject session) throws Exception
 Gets the maximum client buffer size.
static boolean is_BIS_OR_BES_Used ()
 if polish.blackberry
static void purgeEvents (nObject channelimpl, long startEID, long endEID, String selector, boolean sync) throws Exception
 Purges a range of events from this channel.
static void removeAsyncExceptionListener (nObject session) throws Exception
 Removes an already added asynchronous exception listener, which will not be notified of asynchronous exceptions anymore.
static void removeChannelConnectionListener (nObject channel) throws Exception
 Removes an already added channel connection listener, which will not be notified of channel subscriptions/ unsubscriptions anymore.
static void removeQueueListener (nObject queue) throws Exception
 Removes an already added channel subscriber, which will not be notified of events published on the channel anymore.
static void removeSubscriber (nObject channel) throws Exception
 Removes an already added channel subscriber, which will not be notified of events published on the channel anymore.
static void setConnectivityOption (byte option)
 Sets the desired connectivity option flag (INTERNET_APN_OPTION_FLAG or BES_OPTION_FLAG) [Blackberry only].
static void setMaxBufferSize (nObject session, int size) throws Exception
 Sets the maximum client buffer size.
static void setNirvanaProtocolVersion (String protocol)
 Sets the Nirvana wire protocol version.

Static Public Attributes

static final byte BES_OPTION_FLAG = 1
 The BES_OPTION_FLAG when set as a connectivity option, indicates connections occuring via a BES or BIS server [Blackberry only].
static final byte CHAN_MIXED = 3
 Constant for MIXED channel / queue type.
static final byte CHAN_MODE_QUEUE = 101
 Constant for QUEUE channel attribute mode.
static final byte CHAN_PERSISTENT = 2
 Constant for PERSISTENT channel / queue type.
static final byte CHAN_RELIABLE = 1
 Constant for RELIABLE channel / queue type.
static final byte CHAN_SIMPLE = 4
 Constant for SIMPLE channel / queue type.
static final byte INTERNET_APN_OPTION_FLAG = 2
 The INTERNET_APN_OPTION_FLAG when set as a connectivity option, indicates connections occuring via the Internet APN [Blackberry only].
static String scEncoding = null
 Character encoding detected and used by the API.

Protected Member Functions

 nMIDlet ()
 endif

Static Protected Attributes

static final String BES_OR_BIS_SERVER_USED = "BES_OR_BIS_SERVER_USED"
 if polish.blackberry

Detailed Description

Nirvana j2me Client API Package, incorporating pub / sub & message queues This class subclasses MIDlet becoming the new base class for MIDP and IMP applications that wish to use Nirvana.

Constructor & Destructor Documentation

j2meClient.nMIDlet.nMIDlet (  )  [protected]

endif

Default constructor

Member Function Documentation

static void j2meClient.nMIDlet.addAsyncExceptionListener ( nObject  session,
nMIDlet  listener 
) throws Exception [static]

Adds a new asynchronous exception listener, which will be notified when an exception occurs while performing an asynchronous operation.

Parameters:
session the Nirvana session to use
listener The asynchronous exception listener to be added, a subclass of nMIDlet, i.e. your MIDP / IMP application
Exceptions:
Exception is thrown if session is null / of incorrect nObject type

static void j2meClient.nMIDlet.addChannelConnectionListener ( nObject  channel,
nMIDlet  listener 
) throws Exception [static]

Adds a channel connection listener, which will be notified when a new subscriber is added to the channel or an existing subscriber unsubscribes from the channel.

Parameters:
channel the Nirvana channel to use
listener The asynchronous exception listener to be added, a subclass of nMIDlet, i.e. your MIDP / IMP application
Exceptions:
Exception is thrown if channel is null / of incorrect nObject type, or if the listener is null

static void j2meClient.nMIDlet.addQueueListener ( nObject  queue,
nMIDlet  listener,
String  selector 
) throws Exception [static]

Adds an asynchronous channel event listener, which will be notified when events are published on the channel via a callback in the go method.

Parameters:
channel the Nirvana queue to use
listener The asynchronous exception listener to be added, a subclass of nMIDlet, i.e. your MIDP / IMP application
selector A server side message selector or null if all events are required.
Exceptions:
Exception is thrown if channel / namedobject is null / of incorrect nObject type, if the listener is null, if the session is not currently connected to the server, or if the user has insufficient priviledges.

static void j2meClient.nMIDlet.addSubscriber ( nObject  channel,
nMIDlet  listener,
nObject  namedobject,
String  selector,
boolean  AutoAck 
) throws Exception [static]

Adds an asynchronous channel event listener, which will be notified when events are published on the channel via a callback in the go method.

Parameters:
channel the Nirvana queue to use
listener The asynchronous exception listener to be added, a subclass of nMIDlet, i.e. your MIDP / IMP application
namedobject the namedobject to use for this subscription
selector A server side message selector or null if all events are required.
AutoAck a boolean specifying if automatic acknowledgement of events should be performed. If false you need to manually ack each event.
Exceptions:
Exception is thrown if channel / namedobject is null / of incorrect nObject type, if the listener is null, if the session is not currently connected to the server, or if the user has insufficient priviledges.

static void j2meClient.nMIDlet.addSubscriber ( nObject  channel,
nMIDlet  listener,
String  selector,
long  starteid 
) throws Exception [static]

Adds an asynchronous channel event listener, which will be notified when events are published on the channel via a callback in the go method.

Parameters:
channel the Nirvana queue to use
listener The asynchronous exception listener to be added, a subclass of nMIDlet, i.e. your MIDP / IMP application
selector A server side message selector or null if all events are required.
starteid a long specifying which event id to start the subscription. If only events published after subscribing are required, use -1.
Exceptions:
Exception is thrown if channel / namedobject is null / of incorrect nObject type, if the listener is null, if the session is not currently connected to the server, or if the user has insufficient priviledges.

void j2meClient.nMIDlet.delConnection ( String  channelName,
String  connectionId 
)

This method is called asynchronously when a subscription is removed from the nirvana channel.

To change the default behaviour please override this method in your application.

Parameters:
channelName The name of the channel
connectionId The channel connection's ID

Reimplemented in j2meP2PClient.nP2PMIDlet.

void j2meClient.nMIDlet.disconnected ( nObject  anSession  ) 

This method is called asynchronously when a session is disconnected.

If you wish to change the behaviour simply override this method in your application.

Parameters:
anSession The session that got disconnected

Reimplemented in j2meP2PClient.nP2PMIDlet.

static nObject j2meClient.nMIDlet.getChannelSession ( nObject  channelorqueue  )  throws Exception [static]

Registers the specified nEventListener as a subscriber to this channel.

The subscriber will receive all events contained in this channel.

Parameters:
nel the nEventListener object to be registered as a subscriber
Exceptions:
Exception is thrown if the caller has unsufficient permissions Registers the specified nEventListener as a subscriber to this channel. The subscriber will receive all events with event id greater than or equeal to the one specified.
Parameters:
nel the nEventListener object to be registered as a subscriber
eid a long specifying the subscription's start eid
Exceptions:
Exception is thrown if the caller has unsufficient permissions Registers the specified nEventListener as a subscriber to this channel. The subscriber will receive all events contained in this channel, apart from the ones restricted by the specified filter.
Parameters:
nel the nEventListener object to be registered as a subscriber
selector a string specifying a filter to this subscription request
Exceptions:
Exception is thrown if the caller has unsufficient permissions

static String j2meClient.nMIDlet.getConnectionPropertiesSuffix ( String  connectorURL,
byte  connectivityoption 
) [static]

endif

Returns a String suffix of connection properties needed according to the protocol and connectivity options used (Internal Use Only)

static int j2meClient.nMIDlet.getMaxBufferSize ( nObject  session  )  throws Exception [static]

Gets the maximum client buffer size.

This protects your application from running out of memory but also restricts your maximum event size.

The default value is 10 KB

Parameters:
session the session to use
Returns:
an int specifying the current maximum client buffer size
Exceptions:
Exception is thrown if session is null / of incorrect nObject type

abstract void j2meClient.nMIDlet.go ( nObject  consumeevent  )  [pure virtual]

Adds an async listener for this queue.

It will automatically pop the queue and call the listeners go method

Parameters:
nel an nEventListener object Adds an asynchronous queue event listener, which will be notified when events are pushed on the queue via a callback in the go method.
queue the Nirvana queue to use
listener The asynchronous exception listener to be added, a subclass of nMIDlet, i.e. your MIDP / IMP application
selector A server side message selector or null if all events are required.
Exceptions:
Exception is thrown if queue is null / of incorrect nObject type, if the listener is null, if the session is not currently connected to the server, or if the user has insufficient priviledges. Removes an already added queue event listener, which will not be notified of events pushed on the queue anymore.
Parameters:
queue the Nirvana queue to use
Exceptions:
Exception is thrown if queue is null / of incorrect nObject type This method is the callback method for asynchronous events from channels and queues. Please note that processing / delaying the execution of this method prevents the next callback from occuring if any.
Parameters:
consumeevent the consume event received

Implemented in j2meP2PClient.nP2PMIDlet.

void j2meClient.nMIDlet.handleException ( Exception  exception  ) 

This method is called asynchronously when an exception occurs during an asynchronous operation.

Parameters:
exception The exception that occured.

static boolean j2meClient.nMIDlet.is_BIS_OR_BES_Used (  )  [static]

if polish.blackberry

Returns true if a BES / BIS server is used (BES_OPTION_FLAG set), false otherwise. [Blackberry only]

void j2meClient.nMIDlet.newConnection ( String  channelName,
String  connectionId,
String[]  subject,
String  filter,
String  protocol,
String  subscriberName 
)

This method is called asynchronously when a new subscription is registered to a nirvana channel.

To change the default behaviour simply override this method in your application.

Parameters:
connectionId The channel connection's ID
subject A string representation of the subject associated with the channel connection
filter A string representation of the filter associated with the channel connection
protocol A string representation of the protocol (i.e. nsp, nhp, nsps or nhps) associated with the channel connection
subscriberName If the connection is a named subscriber, this is the name associated with that subscription

Reimplemented in j2meP2PClient.nP2PMIDlet.

static void j2meClient.nMIDlet.purgeEvents ( nObject  channelimpl,
long  startEID,
long  endEID,
String  selector,
boolean  sync 
) throws Exception [static]

Purges a range of events from this channel.

Parameters:
startEID a long specifying the start event id of the range of events to be purged from the channel
endEID a long specifying the end event id of the range of events to be purged from the channel
selector A messages selector which will be used to filter out only the events which match this criteria
Exceptions:
Exception is thrown if the caller has unsifficient permissions, or an error occurs

void j2meClient.nMIDlet.reconnected ( nObject  anSession  ) 

Registers the specified nEventListener as a named subscriber to this channel.

The subscriber will receive all events from the last acknowledged event for the name supplied If the name is new it will start from the END of the channel.

Parameters:
nel the nEventListener object to be registered as a subscriber
namedobject a string specifying a name for this subscription
Exceptions:
Exception is thrown if the caller has unsufficient permissions This method is called asynchronously when a session is reconnected. To change the default behavious simply override this method in your application.
Parameters:
anSession The session that got reconnected

Reimplemented in j2meP2PClient.nP2PMIDlet.

static void j2meClient.nMIDlet.removeAsyncExceptionListener ( nObject  session  )  throws Exception [static]

Removes an already added asynchronous exception listener, which will not be notified of asynchronous exceptions anymore.

Parameters:
session the Nirvana session to use
Exceptions:
Exception is thrown if session is null / of incorrect nObject type

static void j2meClient.nMIDlet.removeChannelConnectionListener ( nObject  channel  )  throws Exception [static]

Removes an already added channel connection listener, which will not be notified of channel subscriptions/ unsubscriptions anymore.

Parameters:
channel the Nirvana channel to use
Exceptions:
Exception is thrown if channel is null / of incorrect nObject type

static void j2meClient.nMIDlet.removeQueueListener ( nObject  queue  )  throws Exception [static]

Removes an already added channel subscriber, which will not be notified of events published on the channel anymore.

Parameters:
channel the Nirvana channel to use
Exceptions:
Exception is thrown if channel is null / of incorrect nObject type

static void j2meClient.nMIDlet.removeSubscriber ( nObject  channel  )  throws Exception [static]

Removes an already added channel subscriber, which will not be notified of events published on the channel anymore.

Parameters:
channel the Nirvana channel to use
Exceptions:
Exception is thrown if channel is null / of incorrect nObject type

static void j2meClient.nMIDlet.setMaxBufferSize ( nObject  session,
int  size 
) throws Exception [static]

Sets the maximum client buffer size.

This protects your application from running out of memory but also restricts your maximum event size.

The default value is 10 KB

Parameters:
session the session to use
size an int specifying the new maximum client buffer size in bytes
Exceptions:
Exception is thrown if session is null / of incorrect nObject type

static void j2meClient.nMIDlet.setNirvanaProtocolVersion ( String  protocol  )  [static]

Sets the Nirvana wire protocol version.

Current values are 2 and 3 for Nirvana 2 and Nirvana 3 respectively. The default value is Nirvana 2.

Parameters:
protocol the Nirvana protocol to use

boolean j2meClient.nMIDlet.tryAgain ( nObject  anSession  ) 

This method is called asynchronously between a session being disconnected and a reconnection attempt.

If you wish to use the default reconnect logic, simply return true. If not return false and implement your own custom reconnect logic.

Parameters:
anSession The session to try and reconnect
Returns:
a boolean specifying whether the default reconnect logic should be used or not.

Reimplemented in j2meP2PClient.nP2PMIDlet.