net.rim.blackberry.api.push
Class PushApplicationDescriptor

java.lang.Object
  net.rim.blackberry.api.push.PushApplicationDescriptor

public class PushApplicationDescriptor
extends Object

Enables creating and managing client-side push application descriptor based on application properties.

Descriptor contains the following properties:

• Port number - defines network port number that is used to deliver push messages to the handheld
• Server type - defines server type such as the BlackBerry Push API server (BPAS) which tracks client-side applications and requires application registration procedure
• Server URL (optional) - defines URL to access a server for registration operations. It is used with servers that track client-side push applications such as the BPAS
• Application ID (optional) - defines application ID that uniquely identifies application on the server. It is used with servers that track client-side push applications such as the BPAS
• Application descriptor (optional) - contains arguments that are passed to the main() method for CLDC client-side push applications during automatic startup

Client-side push applications should specify the server type in order to perform registration. If the server does not track applications, for example, the BlackBerry Enterprise Server with no BPAS module, then PushApplicationDescriptor.SERVER_TYPE_NONE value should be used. In this case, there is no registration and client-side push application starts to listen for push messages right away.

If server maintains a database of client-side push applications and requires registration, such as the BPAS database, then the PushApplicationDescriptor.SERVER_TYPE_BPAS constant should be used for specifying the server type. BPAS requires the application ID that was provided during application registration and the server URL which is used for communication during client-side push application registration.

The BPAS may impose registration rules and reject the registration requests. Client-side push application will be notified with registration results. When an application is registered with the BPAS it will be automatically un-registered when user swaps the SIM card. The client-side push application will be notified as well on this event and can re-register if the new user is authorized and wishes to receive push messages.

Since:

BlackBerry API 5.0.0

Field Summary
static byte	SERVER_TYPE_BPAS BlackBerry Push API server (BPAS) type.
static byte	SERVER_TYPE_NONE No server-side support for client-side push applications.

Constructor Summary

PushApplicationDescriptor(int port)
Creates client-side push application descriptor based on given port number only.

PushApplicationDescriptor(int port, ApplicationDescriptor appDescriptor)
Creates push application descriptor based on given port number and application descriptor.

PushApplicationDescriptor(String appId, int port, String serverUrl, byte serverType, ApplicationDescriptor appDescriptor)
Creates push application descriptor based on port number, server type, and application descriptor.

Method Summary
ApplicationDescriptor	getAppDescriptor() Returns the application descriptor that contains arguments passed into the main() method
String	getAppId() Returns the application ID
int	getPort() Returns the network port number to listen to
byte	getServerType() Returns the server type which is either PushApplicationDescriptor.SERVER_TYPE_NONE or PushApplicationDescriptor.SERVER_TYPE_BPAS
String	getServerUrl() Returns the server URL that is used by servers that track client-side push applications.
void	setAppDescriptor(ApplicationDescriptor appDescriptor) Sets the application descriptor that contains arguments passed into the main() method
void	setAppId(String appId) Sets the application ID for servers that track the client-side push applications, such as the BPAS
void	setPort(int port) Sets the network port number to listen to
void	setServerType(byte serverType) Sets the server type that tracks the client-side push applications.
void	setServerUrl(String serverUrl) Sets the server URL that is used for registration.

Methods inherited from class java.lang.Object

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

Field Detail

SERVER_TYPE_NONE

public static final byte SERVER_TYPE_NONE

No server-side support for client-side push applications.

This constant should be used when server doesn't track client applications, such as the BlackBerry Enterprise Server without BPAS. If this constant is used then the library starts listening for incoming messages right away without registering with the server.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

SERVER_TYPE_BPAS

public static final byte SERVER_TYPE_BPAS

BlackBerry Push API server (BPAS) type. This server type tracks subscribed client-side applications and requires application registration.

See Also:

Constant Field Values

Since:

BlackBerry API 5.0.0

Constructor Detail

PushApplicationDescriptor

public PushApplicationDescriptor(int port)

Creates client-side push application descriptor based on given port number only. The current application is used for application descriptor and PushApplicationDescriptor.SERVER_TYPE_NONE for server type

Parameters:

port - port number to listen to for incoming push messages

Since:

BlackBerry API 5.0.0

PushApplicationDescriptor

public PushApplicationDescriptor(int port,
                                 ApplicationDescriptor appDescriptor)

Creates push application descriptor based on given port number and application descriptor. The PushApplicationDescriptor.SERVER_TYPE_NONE is used for server type

Parameters:

port - port number to listen to for incoming push messages

appDescriptor - application descriptor that defines startup arguments passed to the main() method

Since:

BlackBerry API 5.0.0

PushApplicationDescriptor

public PushApplicationDescriptor(String appId,
                                 int port,
                                 String serverUrl,
                                 byte serverType,
                                 ApplicationDescriptor appDescriptor)

Creates push application descriptor based on port number, server type, and application descriptor.

Parameters:

appId - application ID required by the BPAS

port - port number to listen to for incoming push messages

serverUrl - URL that points to the server which tracks client-side push applications

serverType - either the PushApplicationDescriptor.SERVER_TYPE_NONE or PushApplicationDescriptor.SERVER_TYPE_BPAS

appDescriptor - descriptor that specifies parameters passed to client-side push application when it is started

Since:

BlackBerry API 5.0.0

Method Detail

getPort

public int getPort()

Returns the network port number to listen to

Returns:

port number

Since:

BlackBerry API 5.0.0

setPort

public void setPort(int port)

Sets the network port number to listen to

Parameters:

port - new port number to listen to

Since:

BlackBerry API 5.0.0

getServerType

public byte getServerType()

Returns the server type which is either PushApplicationDescriptor.SERVER_TYPE_NONE or PushApplicationDescriptor.SERVER_TYPE_BPAS

Since:

BlackBerry API 5.0.0

setServerType

public void setServerType(byte serverType)

Sets the server type that tracks the client-side push applications. Possible values are either PushApplicationDescriptor.SERVER_TYPE_BPAS or PushApplicationDescriptor.SERVER_TYPE_NONE.

Parameters:

serverType -

Since:

BlackBerry API 5.0.0

getAppDescriptor

public ApplicationDescriptor getAppDescriptor()

Returns the application descriptor that contains arguments passed into the main() method

Since:

BlackBerry API 5.0.0

setAppDescriptor

public void setAppDescriptor(ApplicationDescriptor appDescriptor)

Sets the application descriptor that contains arguments passed into the main() method

Parameters:

appDescriptor - new descriptor with arguments

Since:

BlackBerry API 5.0.0

getAppId

public String getAppId()

Returns the application ID

Since:

BlackBerry API 5.0.0

setAppId

public void setAppId(String appId)

Sets the application ID for servers that track the client-side push applications, such as the BPAS

Parameters:

appId -

Since:

BlackBerry API 5.0.0

getServerUrl

public String getServerUrl()

Returns the server URL that is used by servers that track client-side push applications.

Since:

BlackBerry API 5.0.0

setServerUrl

public void setServerUrl(String serverUrl)

Sets the server URL that is used for registration. This is required if client-side push applications are tracked by a server.

Parameters:

serverUrl -

Since:

BlackBerry API 5.0.0