org.dvb.application
Class AppsDatabase

java.lang.Object
  extended by org.dvb.application.AppsDatabase

public class AppsDatabase
extends java.lang.Object

The AppsDatabase is an abstract view of the currently available applications. The entries will be provided by the application manager, and gleaned from the AIT signaling. When the service context in which an application is running undergoes service selection, instances of AppsDatabase used by that application shall be updated from the new service before an AppsDatabaseEvent is sent to the newDatabase method of any registered AppsDatabaseEventListeners. For applications fully signalled in the current service (i.e. excluding externally authorised ones), the attributes entries shall be the ones from the signalling of the current service even if the application was originally launched from another service and then survived service selection. For running externally authorised applications, the entries will be those from the last service in which they ran fully signalled.

Externally authorized applications shall not appear unless an instance of that application is actually running.

A generic launcher may be written which uses the database to display information in AppAttributes and uses an AppProxy to launch it

Methods on classes in this package do not block, they return the information the system currently has. Therefore applications should be aware that data may be stale, to within one refresh period of the AIT.

e.g.:

  

 
   AppsDatabase theDatabase = AppsDatabase.getAppsDatabase();
   if (theDatabase != null ) {
       CurrentServiceFilter filter = new CurrentServiceFilter();
       Enumeration attributes = theDatabase.getAppAttributes(filter)
       if(attributes != null) {
          while(attributes.hasMoreElements()) {
              AppAttributes info ;
              AppProxy proxy ;
    
              info = (AppAttributes)attributes.nextElement();
              proxy = (AppProxy)theDatabase.getAppProxy(info.getIdentifier());
              AppIcon icon = info.getAppIcon();
              // blah blah..
              // lets start it.
              proxy.start();
          }
       }
   }
 





















 
Where methods on this class as specified as working on "available" applications or "currently available" applications the following definition shall apply. An application is "currently available" if and only if one of the following applies in the service context within which the application calling the method is executing and the visibility of the application is not '00'.. In addition to the methods listed below, all calls made using an AppsDatabaseFilter shall only use that filter to test "currently available" applications as defined here.

Applications whose information (e.g. signaling) is invalid (e.g. one or more mandatory descriptors are missing or incorrect) may not be listed in the AppsDatabase. Where applications are signalled in a broadcast AIT and the GEM terminal tunes away from the service on which the AIT is carried, but without selecting a new service, the AppsDatabase shall retain the entries as signalled in that AIT until a new service is selected.


Method Summary
 void addListener(AppsDatabaseEventListener listener)
          Add a listener to the database so that an application can be informed if the database changes.
 AppAttributes getAppAttributes(AppID key)
          Returns the properties associated with the given ID.
 java.util.Enumeration getAppAttributes(AppsDatabaseFilter filter)
          Returns an enumeration of AppAttributes of the applications available.
 java.util.Enumeration getAppIDs(AppsDatabaseFilter filter)
          Returns an enumeration of the application IDs available.
 AppProxy getAppProxy(AppID key)
          Returns the ApplicationProxy associated with the given ID.
static AppsDatabase getAppsDatabase()
          Returns the singleton AppsDatabase object.
 void removeListener(AppsDatabaseEventListener listener)
          remove a listener on the database.
 int size()
          Returns the number of applications currently available.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getAppsDatabase

public static AppsDatabase getAppsDatabase()
Returns the singleton AppsDatabase object. The AppsDatabase is either a singleton for each GEM application or a singleton for the GEM terminal.

Returns:
the singleton AppsDatabase object.
Since:
MHP1.0

size

public int size()
Returns the number of applications currently available.

Returns:
the number of applications currently available.
Since:
MHP1.0

getAppIDs

public java.util.Enumeration getAppIDs(AppsDatabaseFilter filter)
Returns an enumeration of the application IDs available. The Enumeration will contain the set of AppID that match the filtering criteria. For implementations conforming to this version of the specification, only CurrentServiceFilter or RunningApplicationsFilter filters may return a non empty Enumeration. If the filter object is not an instance of CurrentServiceFilter or RunningApplicationsFilter or one of their subclasses then, the method shall return an empty Enumeration.

This method shall return instances which reflect the contents of the database at the time the method is called. After an AppsDatabaseEvent has been generated, new instances may be returned. After a service selection has taken place, applications which survived the service selection may call this method in order to discover the identities of the applications signalled on the new service.

This method will return an empty Enumeration if there are no matching applications.

Parameters:
filter - the filter to apply
Returns:
the applications available matching the filtering criteria
Since:
MHP1.0

getAppAttributes

public java.util.Enumeration getAppAttributes(AppsDatabaseFilter filter)
Returns an enumeration of AppAttributes of the applications available. The Enumeration will contain the set of AppAttributes that satisfy the filtering criteria. For implementations conforming to this version of the specification, only CurrentServiceFilter or RunningApplicationsFilter filters may return a non empty Enumeration. If the filter object is not an instance of CurrentServiceFilter or RunningApplicationsFilter or a subclass of either then, the method shall return an empty Enumeration.

This method shall return instances which reflect the contents of the database at the time the method is called. After an AppsDatabaseEvent has been generated, new instances may be returned. After a service selection has taken place, applications which survived the service selection may call this method in order to discover the attributes of the applications signalled on the new service.

This method will return an empty Enumeration if there are no attributes.

Parameters:
filter - the filter to apply
Returns:
an enumeration of the applications attributes.
Since:
MHP1.0

getAppAttributes

public AppAttributes getAppAttributes(AppID key)
Returns the properties associated with the given ID. Returns null if no such application is available.

Only one AppAttributes object shall be returned in the case where there are several applications having the same (organisationId, applicationId) pair. In such a case, the same algorithm as would be used to autostart such applications shall be used to decide between the available choices by the implementation.

This method shall return instances which reflect the contents of the database at the time the method is called. After an AppsDatabaseEvent has been generated, new instances may be returned. After a service selection has taken place, applications which survived the service selection may call this method in order to discover the attributes of the applications signalled on the new service.

Parameters:
key - an application ID.
Returns:
the value to which the key is mapped in this dictionary if AppId corresponds to an application which is either a currently available application or remote application or both. Null otherwise.
Since:
MHP1.0

getAppProxy

public AppProxy getAppProxy(AppID key)
Returns the ApplicationProxy associated with the given ID. Returns null if no such application available.

Only one AppProxy object shall be returned in the case where there are several applications having the same (organisationId, applicationId) pair. In such a case, the same algorithm as would be used to autostart such applications shall be used to decide between the available choices by the implementation.

If an application has an application instance in the destroyed state then a proxy for that appplication instance shall not be retrieved. Instead, what shall be retrieved is a proxy for another application instance which shall be in the not loaded state unless that application instance has already been started.

Parameters:
key - an application ID
Returns:
the AppProxy associated with the key parameter or null if the key is not an application ID, or not mapped to any application available.
Throws:
java.lang.SecurityException - shall not be thrown for AppIDs which are returned by getAppIDs(CurrentServiceFilter) or getAppIDs(RunningApplicationsFilter)
Since:
MHP1.0

addListener

public void addListener(AppsDatabaseEventListener listener)
Add a listener to the database so that an application can be informed if the database changes.

Parameters:
listener - the listener to be added.
Since:
MHP1.0

removeListener

public void removeListener(AppsDatabaseEventListener listener)
remove a listener on the database.

Parameters:
listener - the listener to be removed.
Since:
MHP1.0