javax.microedition.broadcast.esg
Interface ServiceGuideData

All Known Subinterfaces:

ProgramEvent, PurchaseObject, Service, ServiceComponent

public interface ServiceGuideData

ServiceGuideData represents an abstract object in an Electronic Service Guide (ESG). ProgramEvent, Service, ServiceComponent and PurchaseObject extend from it to provide the information on an ESG.

ServiceGuideData provides the basic accessor methods to access at different typed attributes.

Some attributes may return multiple matching values. Two versions of most of the accessor methods are provided to access one or multiple matching values: get<type>Value and get<type>Values. If get<type>Value is used on an attribute that specifies multiple values, only one value (the "default") will be returned. Due to the nature of object garbage collection in Java, it is preferrable to use get<type>Value if the attribute is known to only return one value. This is to avoid too many temporary array objects being generated as a result of the accesses.

ServiceComponent differs from ProgramEvent and Service in that instances of it can be get only via ServiceContext while the broadcast is on. ServiceComponent is indirectly visible in ServiceGuide since CommonMetadataSet.SERVICE_COMPONENT_* attributes can be used to query ProgramEvents and Services. It is possible that that ServiceComponent data visible in ServiceGuide differs from the data get from ServiceComponent instances from ServiceContext. In those cases the application should rely on the data from ServiceComponent instances.

If the given attribute is not applicable to the particular broadcast specifications the current service guide is based or the whole service guide data attached to the used ServiceGuideData instance is not available the accessor method will throw an IllegalArgumentException. If the attribute is applicable but there is no data for the given attribute then the accessor method throws an DataUnavailableException.

For instance, application makes a query to the ESG to find services and then changes the platform provider causing the old ESG to be deleted and a completely one to be downloaded. Now, quering data for the services from the original ESG will result into IllegalArgumentException to be thrown even if the used attribute would have been valid for the original ESG.

Notice that it is implementation specific if the old ESG data is deleted when, for example, the platform provider is changed. In addition, if the platform provider is changed back to the original and the original ESG is downloaded again it is not guaranteed that the ServiceGuideData instances fetched before the platform provider changes can be used any longer. Applications are advised to make new queries to the ESG in these kind of situations.

Method Summary

boolean	equals(java.lang.Object data) Compares two ServiceGuideData objects to see if they represent the same service guide information.
MetadataSet[]	getAvailableMetadataSets() Get the list of MetadataSet specs currently available for this ServiceGuideData instance.
boolean	getBooleanValue(BooleanAttribute attribute) Get the value of a boolean attribute.
boolean[]	getBooleanValues(BooleanAttribute attribute) Get one or more values of a boolean attribute.
java.util.Date	getDateValue(DateAttribute attribute) Get the value of a date attribute.
java.util.Date[]	getDateValues(DateAttribute attribute) Get one or more values of a date attribute.
double	getDoubleValue(NumericAttribute attribute) Get the double value of a numeric attribute.
double[]	getDoubleValues(NumericAttribute attribute) Get one or more values of a double attribute.
long	getLongValue(NumericAttribute attribute) Get the long value of a numeric attribute.
long[]	getLongValues(NumericAttribute attribute) Get one or more long values of a numeric attribute.
java.lang.Object	getObjectValue(ObjectAttribute attribute) Get the value of a generic attribute.
java.lang.Object[]	getObjectValues(ObjectAttribute attribute) Get one or more values of a generic attribute.
java.lang.String	getStringValue(StringAttribute attribute) Get the value of a string attribute.
java.lang.String[]	getStringValues(StringAttribute attribute) Get one or more values of a string attribute.

Method Detail

equals

boolean equals(java.lang.Object data)

Compares two ServiceGuideData objects to see if they represent the same service guide information.

Overrides:

equals in class java.lang.Object

Returns:

true if the given ServiceGuideData represents the same service guide information as this object.

getAvailableMetadataSets

MetadataSet[] getAvailableMetadataSets()

Get the list of MetadataSet specs currently available for this ServiceGuideData instance. Available MetadataSets may vary depending on the availability of the associated ServiceGuide.

Returns:

An array of currently available MetadataSets. An empty array is returned if the service guide associated to this ServiceGuideData is not available.

getBooleanValue

boolean getBooleanValue(BooleanAttribute attribute)
                        throws java.lang.IllegalArgumentException,
                               DataUnavailableException

Get the value of a boolean attribute.

Parameters:

attribute - boolean attribute to query the data for.

Returns:

The boolean value of the given attribute.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.

getBooleanValues

boolean[] getBooleanValues(BooleanAttribute attribute)
                           throws java.lang.IllegalArgumentException,
                                  DataUnavailableException

Get one or more values of a boolean attribute.

Parameters:

attribute - boolean attribute to query the data for.

Returns:

An array of boolean values of the given attribute. The returned array contains at least one value.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.

getDateValue

java.util.Date getDateValue(DateAttribute attribute)
                            throws java.lang.IllegalArgumentException,
                                   DataUnavailableException

Get the value of a date attribute.

Parameters:

attribute - date attribute to query the data for.

Returns:

The date value of the given attribute. If the attribute specifies multiple values the returned value is the first one in the array that is returned from getDateValues(DateAttribute attribute) method.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.

getDateValues

java.util.Date[] getDateValues(DateAttribute attribute)
                               throws java.lang.IllegalArgumentException,
                                      DataUnavailableException

Get one or more values of a date attribute.

Parameters:

attribute - date attribute to query the data for.

Returns:

An array of date values of the given attribute. The returned array contains at least one Date.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.

getDoubleValue

double getDoubleValue(NumericAttribute attribute)
                      throws java.lang.IllegalArgumentException,
                             DataUnavailableException

Get the double value of a numeric attribute.

Parameters:

attribute - numeric attribute to query the data for.

Returns:

The double value of the given attribute. If the attribute specifies multiple values the returned value is the first one in the array that is returned from getDoubleValues(NumericAttribute attribute) method.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.

getDoubleValues

double[] getDoubleValues(NumericAttribute attribute)
                         throws java.lang.IllegalArgumentException,
                                DataUnavailableException

Get one or more values of a double attribute.

Parameters:

attribute - numeric attribute to query the data for.

Returns:

An array of double values of the given attribute. Returned array contains at least one value.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.

getLongValue

long getLongValue(NumericAttribute attribute)
                  throws java.lang.IllegalArgumentException,
                         DataUnavailableException

Get the long value of a numeric attribute.

Parameters:

attribute - numeric attribute to query the data for.

Returns:

The long value of the given attribute. If the attribute specifies multiple values the returned value is the first one in the array that is returned from getLongValues(NumericAttribute attribute) method. If NumericAttribute is referring to double the return value is changed to long by casting.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.

getLongValues

long[] getLongValues(NumericAttribute attribute)
                     throws java.lang.IllegalArgumentException,
                            DataUnavailableException

Get one or more long values of a numeric attribute.

Parameters:

attribute - numeric attribute to query the data for.

Returns:

An array of long values of the given attribute. Returned array contains at least one long value. If NumericAttribute is referring to double the return values are changed to long by casting.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.

getObjectValue

java.lang.Object getObjectValue(ObjectAttribute attribute)
                                throws java.lang.IllegalArgumentException,
                                       DataUnavailableException

Get the value of a generic attribute. Since a generic attribute does not identify the type, the value returned is of type java.lang.Object. It's up to the application to determine its type by using instanceof, for example.

Parameters:

attribute - object attribute to query the data for.

Returns:

The value of the given generic attribute. If the attribute specifies multiple values the returned value is the first one in the array that is returned from getObjectValues(ObjectAttribute attribute) method.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.

getObjectValues

java.lang.Object[] getObjectValues(ObjectAttribute attribute)
                                   throws java.lang.IllegalArgumentException,
                                          DataUnavailableException

Get one or more values of a generic attribute. Since a generic attribute does not identify the type, the value returned is of type java.lang.Object. It's up to the application to determine its type by using instanceof, for example.

Parameters:

attribute - object attribute to query the data for.

Returns:

An array of Object values of the given generic attribute. The returned array contains at least one Object.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.

getStringValue

java.lang.String getStringValue(StringAttribute attribute)
                                throws java.lang.IllegalArgumentException,
                                       DataUnavailableException

Get the value of a string attribute.

Parameters:

attribute - string attribute to query the data for.

Returns:

The string value of the given attribute. If the attribute specifies multiple values the returned value is the first one in the array that is returned from getStringValues(StringAttribute attribute) method.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.

getStringValues

java.lang.String[] getStringValues(StringAttribute attribute)
                                   throws java.lang.IllegalArgumentException,
                                          DataUnavailableException

Get one or more values of a string attribute.

Parameters:

attribute - string attribute to query the data for.

Returns:

An array of string values of the given attribute. Returned array contains at least one String.

Throws:

java.lang.NullPointerException - Thrown if the given attribute is null.

java.lang.IllegalArgumentException - Thrown if the given attribute is not valid or the ServiceGuideData is deleted.

DataUnavailableException - Thrown if there is no data for the given attribute.