org.dvb.spi.ict
Interface ResourceTransportObject


public interface ResourceTransportObject

This interface represents a reference to a resource that will be downloaded using an interaction channel transport service provider. It exposes a set of methods that correspond with those in org.dvb.dsmcc.DSMCCObject, so that the applications can use DSMCCObject to reference resources that will be downloaded by the GEM implementation via the service provider implementation.

Like DSMCCObject, ResourceTransportObject instances can either be in a loaded or unloaded state. When in a loaded state, the contents of the resource can be accessed either directly from memory as a byte array or else from a physical file in a local file system (could also be a RAM-based file system).

Note that unlike DSMCCObject instances, resource transport objects are only used to download resources with associated content (i.e. not for URIs that represent directories).


Field Summary
static int LOAD_TYPE_FILE
          Resource load type that indicates the file has been loaded to a local physical file system.
static int LOAD_TYPE_MEMORY
          Resource load type that indicates the file has been loaded in memory as a byte array.
 
Method Summary
 void abort()
          This method is used to abort a load in progress.
 void addUpdateListener(ResourceUpdateListener listener)
          Add a listener to receive notifications of updates to this resource.
 void asynchronousLoad(AsyncResourceLoadListener listener)
          Load the resource asynchronously.
 boolean exists()
          Return a flag indicating whether the resource exists.
 long getLength()
          Return the length in bytes of content of this resource.
 java.lang.String getMimeType()
          Return the MIME type of the resource.
 byte[] getResourceBytes()
          Return a byte array containing the downloaded resource.
 java.io.File getResourceFile()
          Return the resource file containing the downloaded resource.
 int getResourceLoadType()
          Return a value indicating where the associated resource has been downloaded.
 java.lang.String getURI()
          Return the URI identifying the resource to be downloaded.
 boolean isLoaded()
          Return a flag indicating whether the resource has been succesfully downloaded.
 boolean isMetadataLoaded()
          Return a flag indicating whether the metadata for this resource (existence flag, content length, and MIME type) is available for retrieval via the corresponding accessor methods.
 void loadMetadata(AsyncResourceLoadListener listener)
          Load the resource metadata (existence flag, content length, and MIME type) for this resource.
 void removeUpdateListener(ResourceUpdateListener listener)
          Remove a listener that is currently receiving notifications of updates to this resource.
 void synchronousLoad()
          Load the resource.
 void unload()
          Tells the service provider that the downloaded resource object is no longer used, and therefore any resources allocated to this object can be freed.
 

Field Detail

LOAD_TYPE_MEMORY

static final int LOAD_TYPE_MEMORY
Resource load type that indicates the file has been loaded in memory as a byte array.

See Also:
Constant Field Values

LOAD_TYPE_FILE

static final int LOAD_TYPE_FILE
Resource load type that indicates the file has been loaded to a local physical file system.

See Also:
Constant Field Values
Method Detail

getURI

java.lang.String getURI()
Return the URI identifying the resource to be downloaded.

Returns:
String the URI for this resource

addUpdateListener

void addUpdateListener(ResourceUpdateListener listener)
Add a listener to receive notifications of updates to this resource. Note that update notifications will not be fired until after the object has succcessfully entered the loaded state for the first time.

Once an object has successfully entered the loaded state once, this event shall continue to be fired when changes are detected regardless of further transitions in or out of the loaded state.

Parameters:
listener - the listener to be added

removeUpdateListener

void removeUpdateListener(ResourceUpdateListener listener)
Remove a listener that is currently receiving notifications of updates to this resource. If the specified listener has not previously been added, then calling this method has no effect.

Parameters:
listener - the listener to be removed

synchronousLoad

void synchronousLoad()
                     throws ResourceLoadException
Load the resource. When this method returns, the resource will have been succesfully downloaded. If the download fails, then a ResourceLoadException will be thrown.

Throws:
ResourceLoadException

asynchronousLoad

void asynchronousLoad(AsyncResourceLoadListener listener)
Load the resource asynchronously. The specified listener will be notified of the loading progress, including subsequent successful completion or failure.

Parameters:
listener - the listener to be notified

isLoaded

boolean isLoaded()
Return a flag indicating whether the resource has been succesfully downloaded.


isMetadataLoaded

boolean isMetadataLoaded()
Return a flag indicating whether the metadata for this resource (existence flag, content length, and MIME type) is available for retrieval via the corresponding accessor methods. Depending on the specifics of the provider implementation and transport mechanism, it may be that this information is available without needing to call the loadMetadata method; that method should be called only when this method returns false.

Returns:
boolean - Flag indicating whether the metadata for this resource has been loaded and is ready for retrieval via relevant accessor methods

getResourceLoadType

int getResourceLoadType()
Return a value indicating where the associated resource has been downloaded. Possible values include:

LOAD_TYPE_MEMORY - indicates that the resource was loaded into memory as a byte array, and can be retrieved using the getResourceBytes() method.

  • LOAD_TYPE_FILE - indicates that the resource was loaded to a file on a local physical file system, and can be retrieved using the getResourceFile() method.

    Returns:
    int - the load type
    Throws:
    java.lang.IllegalStateException - if the resource is not loaded

  • getResourceFile

    java.io.File getResourceFile()
    Return the resource file containing the downloaded resource. This method should only be called if the resource is loaded and getResourceLoadType() returns LOAD_TYPE_FILE.

    The provider must ensure that the returned file is readable by the GEM implementation.

    Returns:
    File - the resource load file
    Throws:
    java.lang.IllegalStateException - if the resource is not loaded or is loaded to a byte array in memory

    getResourceBytes

    byte[] getResourceBytes()
    Return a byte array containing the downloaded resource. This method should only be called if the resource is loaded and getResourceLoadType() returns LOAD_TYPE_MEMORY.

    Returns:
    byte [] the resource data
    Throws:
    java.lang.IllegalStateException - if the resource is not loaded or is loaded to a file

    abort

    void abort()
    This method is used to abort a load in progress. It can be used to abort either a synchronousLoad or an asynchronousLoad.

    Throws:
    java.lang.IllegalStateException - if load of the resource has not already been started

    unload

    void unload()
    Tells the service provider that the downloaded resource object is no longer used, and therefore any resources allocated to this object can be freed. This method puts the ResourceTransportObject back into the unloaded state.

    Throws:
    java.lang.IllegalStateException - if the resource is not loaded

    loadMetadata

    void loadMetadata(AsyncResourceLoadListener listener)
                      throws ResourceLoadException
    Load the resource metadata (existence flag, content length, and MIME type) for this resource. Note that some providers will be able to determine the metadata information without downloading the resource content by using cached directory lookup information, but in general this may not be the case. In cases where the provider must download the resource to find the directory information, this call may have an equivalent effect to calling asynchronousLoad(). If a load request is already in progress, this method may also block until the outstanding load request is complete.

    This method may fail either asynchronously with notification event sent to the listener or else synchronously during this method call.

    Once the metadata is loaded, the following methods may be called:

    Parameters:
    listener - A listener to be notified of asynchronous loading events.
    Throws:
    ResourceLoadException

    exists

    boolean exists()
    Return a flag indicating whether the resource exists. Note that some providers may be able to determine resource existence without downloading the resource using cached directory lookup information, but in general this may not be the case. In cases where the provider must download the resource to determine resource existence, this call may result in a synchronous load operation being performed before returning.

    Returns:
    boolean

    getMimeType

    java.lang.String getMimeType()
    Return the MIME type of the resource. Note that some providers may be able to determine the MIME type without downloading the resource using cached directory lookup information, but in general this may not be the case. In cases where the provider must download the resource to determine the MIME type, this call may result in a synchronous load operation being performed before returning.

    Returns:
    String

    getLength

    long getLength()
    Return the length in bytes of content of this resource. Note that some providers may be able to determine the size without downloading the resource using cached directory lookup informatino, but in general this may not be the case. In cases where the provider must download the resource to determine the length, this call may result in a synchronous load operation being performed before returning. In addition, since this information may be populated from a directory, it is not guaranteed to be accurate; the most authoritative information is specified after download from either getResourceBytes().length or getResourceFile().length(), depending on the load type.

    Returns:
    long the length in bytes of the resource content