javax.microedition.broadcast.purchase
Class SubscriptionManager

java.lang.Object
  javax.microedition.broadcast.purchase.SubscriptionManager

public class SubscriptionManager
extends java.lang.Object

The SubscriptionManager is used to manage purchase settings and existing subscriptions.

Purchasing is done by either getting a list of available purchase bundles via getAllPurchaseObjects(), or by querying the purchase options for individual program events or services via getPurchaseObjects(String id). The id of a program event or service is obtained from a ProgramEvent or Service, respectively. Purchase bundle is a collection of services or program events or both that can purchased by a single purchase transaction. Purchase bundle is represented by a PurchaseObject.

The incomplete code snippet below shows how to get a PurchaseObject for selected service for purchase. It is assumed that the implementation supports CommonMetadataSet.SERVICE_ID attribute.

 Service service;

 // getting the service from the ESG
 ...

 String serviceId = service.getStringValue(CommonMetadataSet.SERVICE_ID);
 PurchaseObjects[] purchaseObjects = SubscriptionManager.getPurchaseObjects(serviceId);

  
 

Similarly, the PurchaseObjects for ProgramEvents can be get by passing the CommonMetadataSet.PROGRAM_ID to the getPurchaseObjects(String id) method.

Existing subscriptions can be queried by getSubscriptions(). Method returns a list of PurchaseObjects that identify the purchased services.

In order to see what exactly the purchase or subscription contains the application can fetch the services and programs from the PurchaseObject

 String[] servicesIDs = purchaseObjects[0].getStringValues(CommonMetadataSet.SERVICE_ID);
 String[] programIDs = purchaseObjects[0].getStringValues(CommonMetadataSet.PROGRAM_ID);
 

SubscriptionManager specifies two PlayerListener events to indicate Players about Rights Object related issues. More comprehensive explanation about them is found from Security, DRM and Purchasing Specification.

Purchasing functionality can't be guaranteed to work all the time, or at all. On some platforms purchasing maybe is not applicable at all. It's also possible that, for instance, change of platform provider affects the purchasing functionality. SubscriptionManager methods will always work but occasionally methods returning arrays may return an empty array and getDefaultPurchaseChannel() may return null.

Support for purchasing

All implementations don't necessarily support purchasing. System property microedition.broadcast.supports.purchasing can be used to query if purchasing is supported or not.

If purchasing is not supported then

• System property microedition.broadcast.supports.purchasing returns false.
• All methods in this class will throw UnsupportedOperationException when called

Field Summary

static java.lang.String	NO_RIGHTS Posted to a PlayerListener when Player is trying to play content that the application has no rights to.
static java.lang.String	RIGHTS_UPDATED Posted to a PlayerListener when the Rights Object associated to the Service or ProgramEvent used by the Player has been updated.

Method Summary

static PurchaseObject[]	getAllPurchaseObjects() Get all available PurchaseObjects.
static java.lang.String	getDefaultPurchaseChannel() Get the channel of the default purchase system used for purchase requests.
static PurchaseObject[]	getPurchaseObjects(java.lang.String id) Get all PurchaseObjects to purchase a Service or ProgramEvent It may be possible to purchase the service via multiple service bundles so multiple PurchaseObjects may be returned.
static PurchaseObject[]	getSubscriptions() Get purchased subscriptions.
static java.lang.String[]	getSupportedPurchaseChannels() Get the supported purchase channels.

Methods inherited from class java.lang.Object

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

Field Detail

NO_RIGHTS

public static final java.lang.String NO_RIGHTS

Posted to a PlayerListener when Player is trying to play content that the application has no rights to.

See Also:

Constant Field Values

RIGHTS_UPDATED

public static final java.lang.String RIGHTS_UPDATED

Posted to a PlayerListener when the Rights Object associated to the Service or ProgramEvent used by the Player has been updated.

See Also:

Constant Field Values

Method Detail

getAllPurchaseObjects

public static PurchaseObject[] getAllPurchaseObjects()
                                              throws UnsupportedOperationException

Get all available PurchaseObjects. The returned list may contain already purchased PurchaseObjects.

Returns:

all available PurchaseObjects.

Throws:

UnsupportedOperationException - if purchasing is not supported.

getDefaultPurchaseChannel

public static java.lang.String getDefaultPurchaseChannel()
                                                  throws UnsupportedOperationException

Get the channel of the default purchase system used for purchase requests. PurchaseObjects returned by SubscriptionManager use the current default purchase channel. Default purchase channel may change over time, for instance, because the platform provider is changed.

Returns:

URI of the default purchase channel or null if purchasing is supported but for some reason the default purchase channel is currently not known.

Throws:

UnsupportedOperationException - if purchasing is not supported.

getPurchaseObjects

public static PurchaseObject[] getPurchaseObjects(java.lang.String id)
                                           throws UnsupportedOperationException

Get all PurchaseObjects to purchase a Service or ProgramEvent It may be possible to purchase the service via multiple service bundles so multiple PurchaseObjects may be returned.

Parameters:

id - the SERVICE_ID or the PROGRAM_ID of the Service or ProgramEvent, respectively, to be purchased.

Returns:

PurchaseObjects containing the required Service or ProgramEvent.

Throws:

java.lang.NullPointerException - if id is null.

java.lang.IllegalArgumentException - if id is not valid.

UnsupportedOperationException - if purchasing is not supported.

getSubscriptions

public static PurchaseObject[] getSubscriptions()
                                         throws UnsupportedOperationException,
                                                java.lang.SecurityException

Get purchased subscriptions. List of purchased subscription may be depending, for instance, on the platform provider.

Returns:

an array of PurchaseObjects containing purchased services.

Throws:

UnsupportedOperationException - if purchasing is not supported.

java.lang.SecurityException - if user has no rights to query subscriptions.

getSupportedPurchaseChannels

public static java.lang.String[] getSupportedPurchaseChannels()
                                                       throws UnsupportedOperationException

Get the supported purchase channels.

Returns:

URIs to identify the supported purchase channels

Throws:

UnsupportedOperationException - if purchasing is not supported.