org.dvb.dsmcc

Class DSMCCObject

java.lang.Object

java.io.File

org.dvb.dsmcc.DSMCCObject

All Implemented Interfaces:

Serializable, Comparable

public class DSMCCObject
extends File

A DSMCCObject extends the java.io.File class with a combination of features appropriate for any file system with a long access time and features specific to the DSMCC object carousel as one example of such a file system. Files referenced by a DSMCCObject exist within a file system. This may be represented by an instance of ServiceDomain but need not be, particularly for the file system in which the initial file of the application itself is carried.

A DSMCCObject is specified by a pathname, which can either be an absolute pathname or a relative pathname. Relative paths shall work as defined in "Broadcast Transport Protocol Access API" in the main body of the present document. Path names must follow the naming conventions of the host platform. The constructors of this class shall accept the absolute paths returned by java.io.File.getAbsolutePath().

To access the content of the object:

• For a Directory, the method list of the java.io.File class has to be used to get the entries of the directory.
• For a Stream object, the class DSMCCStream has to be used.
• For a File, the java.io.FileInputStream class or the java.io.RandomAccessFile has to be used.

NB:

• Obviously, for the Object Carousel, the write mode of java.io.RandomAccessFile is not allowed.

DSMCCObjects exist in two states, loaded and unloaded as returned by the isLoaded method. Transitions from unloaded to loaded are triggered by applications calling the asynchronousLoad or synchronousLoad or getSigners(boolean) methods. Transitions from loaded to unloaded are triggered by applications calling the unload method. Attempting to load an already loaded object does not cause it to be re-loaded.

The only state transitions for a DSMCCObject shall be only in response to these method calls. There shall be no implicit state transitions in either direction. When the application no longer has any references to an object in the loaded state, the system resources allocated should be freed by the system.

The state machine of DSMCCObject is disconnected from any state model of any cache for the file system that contains it. Objects may appear in that cache without any corresponding DSMCCObject being in the loaded state. Objects which are in that cache and where any corresponding DSMCCObject is not in the loaded state may disappear from that cache at any time. The contents of a object may be accessible to applications from the cache without the DSMCCObject ever being in the loaded state.

NOTE: DSMCCObjects in the loaded state will consume memory in the MHP receiver. If memory in the MHP receiver is short, this memory can only be recovered by the receiver killing the MHP application. Applications which can accept weaker guarantees about the data of a DSMCCObject being available should use the prefetch methods.

See Also:

ServiceDomain, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static int	FORCED_STATIC_CACHING Constant to indicate that the data for an object shall be returned from the cache if present, disregarding the cache priority signalling.
static int	FROM_CACHE Constant to indicate that the data for an object shall only be retrieved where it is already in cache and meets the requirements of cache priority signaling.
static int	FROM_CACHE_OR_STREAM Constant to indicate that the data for an object shall be automatically be retrieved from the network where the data is not already cached.
static int	FROM_STREAM_ONLY Constant to indicate that the data for an object shall always be retrieved from the network even if the data has already been cached.

Fields inherited from class java.io.File

pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

Constructors

Constructor and Description
DSMCCObject(DSMCCObject dir, String name) Create a DSMCCObject object.
DSMCCObject(String path) Create a DSMCCObject object.
DSMCCObject(String path, String name) Create a DSMCCObject object.

Method Summary

Methods

Modifier and Type	Method and Description
void	abort() This method is used to abort a load in progress.
void	addObjectChangeEventListener(ObjectChangeEventListener listener) Subscribes an ObjectChangeEventListener to receive notifications of version changes of DSMCCObject.
void	asynchronousLoad(AsynchronousLoadingEventListener l) This method starts the asynchronous loading of the data for a DSMCCObject.
X509Certificate[][]	getSigners() This method shall attempt to validate all certificate chains found for this file in the network.
X509Certificate[][]	getSigners(boolean known_root) This method shall attempt to validate all certificate chains found for this file in the network.
URL	getURL() Returns a URL identifying this carousel object.
boolean	isLoaded() Returns a boolean indicating whether or not the DSMCCObject has been loaded.
boolean	isObjectKindKnown() Returns a boolean indicating if the kind of the object is known.
boolean	isStream() Returns a boolean indicating whether or not the DSMCCObject is a DSMCC Stream object.
boolean	isStreamEvent() Returns a boolean indicating whether or not the DSMCCObject is a DSMCC StreamEvent object.
void	loadDirectoryEntry(AsynchronousLoadingEventListener l) Asynchronous loading of the directory entry information.
static boolean	prefetch(DSMCCObject dir, String path, byte priority) Calling this method will issue a hint to the MHP for pre-fetching the object data for that DSMCC object into cache.
static boolean	prefetch(String path, byte priority) Calling this method will issue a hint to the MHP for pre-fetching the object data for that DSMCC object into cache.
void	removeObjectChangeEventListener(ObjectChangeEventListener listener) Unsubscribes an ObjectChangeEventListener to receive notifications of version changes of DSMCCObject.
void	setRetrievalMode(int retrieval_mode) Set the retrieval mode for a DSMCCObject.
void	synchronousLoad() This method is used to load a DSMCCObject.
void	unload() When calling this method, the applications gives a hint to the MHP that if this object is not consumed by another application/thread, the system can free all the resources allocated to this object.

Methods inherited from class java.io.File

canExecute, canRead, canWrite, compareTo, compareTo, createNewFile, createTempFile, createTempFile, delete, deleteOnExit, equals, exists, getAbsoluteFile, getAbsolutePath, getCanonicalFile, getCanonicalPath, getFreeSpace, getName, getParent, getParentFile, getPath, getTotalSpace, getUsableSpace, hashCode, isAbsolute, isDirectory, isFile, isHidden, lastModified, length, list, list, listFiles, listFiles, listFiles, listRoots, mkdir, mkdirs, renameTo, setExecutable, setExecutable, setLastModified, setReadable, setReadable, setReadOnly, setWritable, setWritable, toPath, toString, toURI, toURL

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

FROM_CACHE

public static final int FROM_CACHE

Constant to indicate that the data for an object shall only be retrieved where it is already in cache and meets the requirements of cache priority signaling. Where data is not in the cache, or the contents do not meet the requirements of the of cache priority signaling (i.e. cache priority signalling indicates that an object re-acquisition is required), attempts to load a DSMCCObject shall fail with MPEGDeliveryException or MPEGDeliveryErrorEvent for synchronousLoad and asynchronousLoad respectively.

Since:

MHP 1.0.1

See Also:

Constant Field Values

FROM_CACHE_OR_STREAM

public static final int FROM_CACHE_OR_STREAM

Constant to indicate that the data for an object shall be automatically be retrieved from the network where the data is not already cached. Note that this method does not modify the caching policy controlled by the signaling in the OC. So, if the data is signalled as requiring transparent caching then data will be retrieved from the network if required.

Since:

MHP 1.0.1

See Also:

Constant Field Values

FROM_STREAM_ONLY

public static final int FROM_STREAM_ONLY

Constant to indicate that the data for an object shall always be retrieved from the network even if the data has already been cached.

NOTE : This functionality is introduced deliberately to bypass any receiver cache allowing an application to be synchronised with the broadcast carousel. It should not be used simply to ensure up-to-date content is retrieved. It should also be noted here that this feature is provided to fulfil very specific application requirements (where other provided methods may not be suitable) and misuse of this functionality may seriously affect application/receiver performance.

Since:

MHP 1.0.1

See Also:

Constant Field Values

FORCED_STATIC_CACHING

public static final int FORCED_STATIC_CACHING

Constant to indicate that the data for an object shall be returned from the cache if present, disregarding the cache priority signalling. If the data is not in the cache, it shall be retrieved from the network.

This strategy is intended solely for situations where generic DVB object carousels (as opposed to MHP object carousels) are being accessed and only the accessing application knows which files are static and which are dynamic. It should not be used to access files in MHP object carousels where the Caching priority descriptor can and should be used.

Since:

MHP 1.1.2

See Also:

Constant Field Values

Constructor Detail

DSMCCObject

public DSMCCObject(String path)

Create a DSMCCObject object.

Parameters:

path - the path to the file.

DSMCCObject

public DSMCCObject(String path,
           String name)

Create a DSMCCObject object.

Parameters:

path - the directory Path.

name - the file pathname.

DSMCCObject

public DSMCCObject(DSMCCObject dir,
           String name)

Create a DSMCCObject object.

Parameters:

dir - the directory object.

name - the file pathname.

Method Detail

isLoaded

public boolean isLoaded()

Returns a boolean indicating whether or not the DSMCCObject has been loaded.

Returns:

true if the file is already loaded, false otherwise.

isStream

public boolean isStream()

Returns a boolean indicating whether or not the DSMCCObject is a DSMCC Stream object.

Returns:

true if the file is a stream, false if the object is not a stream or if the object kind is unknown.

isStreamEvent

public boolean isStreamEvent()

Returns a boolean indicating whether or not the DSMCCObject is a DSMCC StreamEvent object. NB: If isStreamEvent is true then isStream is true also.

Returns:

true if the file is a stream event, false if the object is not a stream event or if the object kind is unknown.

isObjectKindKnown

public boolean isObjectKindKnown()

Returns a boolean indicating if the kind of the object is known. (The kind of an object is known if the directory containing it is loaded).

Returns:

true if the type of the object is known, false otherwise.

synchronousLoad

public void synchronousLoad()
                     throws InvalidFormatException,
                            InterruptedIOException,
                            MPEGDeliveryException,
                            ServerDeliveryException,
                            InvalidPathNameException,
                            NotEntitledException,
                            ServiceXFRException,
                            InsufficientResourcesException

This method is used to load a DSMCCObject. This method blocks until the file is loaded. It can be aborted from another thread with the abort method. In this case the InterruptedIOException is thrown. For DSMCCObjects contained within a DSMCC object carousel, if the IOR of the object itself or one of its parent directories is a Lite Option Profile Body and the referenced carousel is not attached, the MHP implementation will not attempt to resolve it: a ServiceXFRException is thrown to indicate to the application where the DSMCCObject is actually located.

Throws:

InterruptedIOException - the loading has been aborted.

InvalidPathNameException - the Object can not be found, or the service domain is not in an attached state.

NotEntitledException - the stream carrying the object is scrambled and the user has no entitlements to descramble the stream.

ServiceXFRException - the file system containing the DSMCCObject is a DSMCC object carousel and the IOR of the object or one of its parent directories is a Lite Option Profile Body and the referenced carousel is not already mounted by the MHP terminal.

InvalidFormatException - an error occured in the format of the file system containing the DSMCCObject, for instance an inconsistent DSMCC message has been received.

MPEGDeliveryException - an error has occurred while loading data for the file, for instance a timeout when reading data from an MPEG stream

ServerDeliveryException - when an MHP terminal cannot communicate with the server for files delivered over a bi-directional IP connection.

InsufficientResourcesException - there is not enough memory to load the object

asynchronousLoad

public void asynchronousLoad(AsynchronousLoadingEventListener l)
                      throws InvalidPathNameException

This method starts the asynchronous loading of the data for a DSMCCObject. This method can fail either asynchronously with an event or synchronously with an exception. When it fails synchronously with an exception, no event shall be sent to the listener. For each call to this method which returns without throwing an exception, one of the following events will be sent to the application (by a listener mechanism) as soon as the loading is done or if an error has occurred: SuccessEvent, InvalidFormatEvent, InvalidPathNameEvent, MPEGDeliveryErrorEvent, ServerDeliveryErrorEvent, ServiceXFRErrorEvent, NotEntitledEvent, LoadingAbortedEvent, InsufficientResourcesEvent.

Parameters:

l - an AsynchronousLoadingEventListener to receive events related to asynchronous loading.

Throws:

InvalidPathNameException - the Object can not be found, or the service domain is not in an attached state.

abort

public void abort()
           throws NothingToAbortException

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

Throws:

NothingToAbortException - There is no loading in progress.

prefetch

public static boolean prefetch(String path,
               byte priority)

Calling this method will issue a hint to the MHP for pre-fetching the object data for that DSMCC object into cache.

Parameters:

path - the absolute pathname of the object to pre-fetch.

priority - the relative priority of this pre-fetch request (higher = more important)

Returns:

true if the MHP supports pre-fetching (i.e. will try to process the request) and false otherwise. Note that a return value of 'true' is only an indication that the MHP receiver supports pre-fetching. It is not a guarantee that the requested data will actually be loaded into cache as the receiver may decide to drop the request in order to make resources available for regular load requests.

prefetch

public static boolean prefetch(DSMCCObject dir,
               String path,
               byte priority)

Calling this method will issue a hint to the MHP for pre-fetching the object data for that DSMCC object into cache.

Parameters:

dir - the directory object in which to pre-fetch the data.

path - the relative path name of object to pre-fetch, starting from the directory object passes as parameter.

priority - the relative priority of this pre-fetch request (higher = more important)

Returns:

true if the MHP supports pre-fetching (i.e. will try to process the request) and false otherwise. Note that a return value of 'true' is only an indication that the MHP receiver supports pre-fetching. It is not a guarantee that the requested data will actually be loaded into cache as the receiver may decide to drop the request in order to make resources available for regular load requests.

unload

public void unload()
            throws NotLoadedException

When calling this method, the applications gives a hint to the MHP that if this object is not consumed by another application/thread, the system can free all the resources allocated to this object. It is worth noting that if other clients use this object (e.g. a file input stream is opened on this object or if the corresponding stream or stream event is being consumed) the system resources allocated to this object will not be freed. This method puts the DSMCCObject into the unloaded state.

Throws:

NotLoadedException - the carousel object is not loaded.

getURL

public URL getURL()

Returns a URL identifying this carousel object. If the directory entry for the object has not been loaded then null shall be returned.

Returns:

a URL identifying the carousel object or null

Since:

MHP 1.0.1

addObjectChangeEventListener

public void addObjectChangeEventListener(ObjectChangeEventListener listener)
                                  throws InsufficientResourcesException

Subscribes an ObjectChangeEventListener to receive notifications of version changes of DSMCCObject.

This listener shall never be fired until after the object has successfully entered the loaded state for the first time. Hence objects which never successfully enter the loaded state (e.g. because the object cannot be found) shall never have this listener fire. Once an object has successfully entered the loaded state once, this event shall continue to be fired when changes are detected by the MHP regardless of further transitions in or out of the loaded state.

NOTE: The algorithm used for this change monitoring is implementation dependent. In some implementations, this exception will always be thrown. In other implementations, it will never be thrown. In other implementations, whether it is thrown or not will depend on the complexity and design of the object carousel in which the object is carried. Even where no exception is thrown, implementations are not required to detect all possible forms in which an object may change.

Parameters:

listener - the ObjectChangeEventListener to be notified .

Throws:

InsufficientResourcesException - if there are not sufficient resources to monitor the object for changes.

removeObjectChangeEventListener

public void removeObjectChangeEventListener(ObjectChangeEventListener listener)

Unsubscribes an ObjectChangeEventListener to receive notifications of version changes of DSMCCObject.

Parameters:

listener - a previously registered ObjectChangeEventListener.

loadDirectoryEntry

public void loadDirectoryEntry(AsynchronousLoadingEventListener l)
                        throws InvalidPathNameException

Asynchronous loading of the directory entry information. Calling this is equivalent of calling the method asynchronousLoad on the parent directory of a DSMCCObject. This method can fail either asynchronously with an event or synchronously with an exception. When it fails synchronously with an exception, no event shall be sent to the listener.

Parameters:

l - a listener which will be called when the loading is done.

Throws:

InvalidPathNameException - if the object cannot be found.

setRetrievalMode

public void setRetrievalMode(int retrieval_mode)

Set the retrieval mode for a DSMCCObject. The default retrieval mode is FROM_CACHE_OR_STREAM. The retrieval mode state is sampled when the object is loaded (whether explicitly or as described in "Constraints on the java.io.File methods for broadcast carousels"). Changing the retrieval mode for a loaded object has no effect until the object is unloaded and loaded again.

Parameters:

retrieval_mode - the retrieval mode to be used for the object specified as one of the public static final constants in this class.

Throws:

IllegalArgumentException - if the retrieval_mode specified is not one listed defined for use with this method.

Since:

MHP 1.0.1

getSigners

public X509Certificate[][] getSigners()

This method shall attempt to validate all certificate chains found for this file in the network. Valid chains do not need to originate from root certificates known to the MHP terminal, e.g. self signing of data files. Applications should note that calls to this method may take some time. If the DSMCCObject is not loaded, this method will return null. If the DSMCCObject is loaded, this method returns the same as getSigners(false), except if getSigners(false) would throw an exception, this method will return an outer array of size zero.

NOTE: If the file in the network changes between when it was loaded and when the hash file(s), signature & certificate files are read and those files have been updated to match the new version of the file then the hash value of the data which was loaded will not match the hash value in the hash file in the network and hence no certificate chains will be valid.

Returns:

a two-dimensional array of X.509 certificates, where the first index of the array determines a certificate chain and the second index identifies the certificate within the chain. Within one certificate chain the leaf certificate is first followed by any intermediate certificate authorities in the order of the chain with the root CA certificate as the last item.

Since:

MHP 1.0.1

getSigners

public X509Certificate[][] getSigners(boolean known_root)
                               throws InvalidFormatException,
                                      InterruptedIOException,
                                      MPEGDeliveryException,
                                      ServerDeliveryException,
                                      InvalidPathNameException,
                                      NotEntitledException,
                                      ServiceXFRException,
                                      InsufficientResourcesException

This method shall attempt to validate all certificate chains found for this file in the network. The process of determining validity is the same as the process of authentication except that when known_root is false, checking whether the root certificate is known is not included. The known_root parameter to the method defines whether the MHP terminal shall check if the root certificate in each chain is known to it or not. If the root certificate is checked then chains with unknown root certificates shall not be considered to be valid. If root certificates are not checked then the MHP application is responsible for comparing them with some certificate which it provides (e.g. for self signing of data files). The hash file(s), signature & certificate files shall be shall be fetched from the network in compliance with the caching priority defined in the main body of the present document. If the object is in the loaded state then the data of the file which was loaded shall be used and no new file contents loaded. If the object is not in the loaded state then this method shall attempt to load it as if synchronousLoad had been called. Applications should note that calls to this method may take some time.

NOTE: If the file in the network changes between when it was loaded and when the hash file(s), signature & certificate files are read and those files have been updated to match the new version of the file then the hash value of the data which was loaded will not match the hash value in the hash file in the network and hence no certificate chains will be valid.

Parameters:

known_root - if true then valid certificate chains are only those where the root is known to the MHP terminal. If false, the validity of the chain shall be determined without considering whether the root is known to the MHP terminal or not.

Returns:

a two-dimensional array of X.509 certificates, where the first index of the array determines a certificate chain and the second index identifies the certificate within the chain. Within one certificate chain the leaf certificate is first followed by any intermediate certificate authorities in the order of the chain with the root CA certificate as the last item. If no certificate chains are found to be valid then an outer array of size zero shall be returned.

Throws:

InterruptedIOException - the loading has been aborted.

InvalidPathNameException - the Object can not be found, or the service domain is not in an attached state.

NotEntitledException - the stream carrying the object is scrambled and the user has no entitlements to descramble the stream.

ServiceXFRException - the file system containing the DSMCCObject is a DSMCC object carousel and the IOR of the object or one of its parent directories is a Lite Option Profile Body and the referenced carousel is not already mounted by the MHP terminal.

InvalidFormatException - an error occured in the format of the file system containing the DSMCCObject, for instance an inconsistent DSMCC message has been received.

MPEGDeliveryException - an error has occurred while loading data for the file, for instance a timeout when reading data from an MPEG stream

ServerDeliveryException - when an MHP terminal cannot communicate with the server for files delivered over a bi-directional IP connection.

InsufficientResourcesException - there is not enough memory to load the object

Since:

MHP 1.0.3