|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.io.File
org.dvb.dsmcc.DSMCCObject
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:
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.
ServiceDomain
,
Serialized FormField Summary | |
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 | |
DSMCCObject(DSMCCObject dir,
java.lang.String name)
Create a DSMCCObject object. |
|
DSMCCObject(java.lang.String path)
Create a DSMCCObject object. |
|
DSMCCObject(java.lang.String path,
java.lang.String name)
Create a DSMCCObject object. |
Method Summary | |
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. |
java.security.cert.X509Certificate[][] |
getSigners()
This method shall attempt to validate all certificate chains found for this file in the network. |
java.security.cert.X509Certificate[][] |
getSigners(boolean known_root)
This method shall attempt to validate all certificate chains found for this file in the network. |
java.net.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,
java.lang.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(java.lang.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 |
canRead, canWrite, compareTo, compareTo, createNewFile, createTempFile, createTempFile, delete, deleteOnExit, equals, exists, getAbsoluteFile, getAbsolutePath, getCanonicalFile, getCanonicalPath, getName, getParent, getParentFile, getPath, hashCode, isAbsolute, isDirectory, isFile, isHidden, lastModified, length, list, list, listFiles, listFiles, listFiles, listRoots, mkdir, mkdirs, renameTo, setLastModified, setReadOnly, toString, toURI, toURL |
Methods inherited from class java.lang.Object |
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
public static final int FROM_CACHE
MPEGDeliveryException
or MPEGDeliveryErrorEvent
for synchronousLoad and asynchronousLoad respectively.
public static final int FROM_CACHE_OR_STREAM
public static final int FROM_STREAM_ONLY
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.
public static final int FORCED_STATIC_CACHING
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.
Constructor Detail |
public DSMCCObject(java.lang.String path)
path
- the path to the file.public DSMCCObject(java.lang.String path, java.lang.String name)
path
- the directory Path.name
- the file pathname.public DSMCCObject(DSMCCObject dir, java.lang.String name)
dir
- the directory object.name
- the file pathname.Method Detail |
public boolean isLoaded()
public boolean isStream()
public boolean isStreamEvent()
public boolean isObjectKindKnown()
public void synchronousLoad() throws InvalidFormatException, java.io.InterruptedIOException, MPEGDeliveryException, ServerDeliveryException, InvalidPathNameException, NotEntitledException, ServiceXFRException, InsufficientResourcesException
java.io.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 objectpublic void asynchronousLoad(AsynchronousLoadingEventListener l) throws InvalidPathNameException
l
- an AsynchronousLoadingEventListener to receive events related to asynchronous loading.
InvalidPathNameException
- the Object can not be found, or the service domain is not in an attached state.public void abort() throws NothingToAbortException
NothingToAbortException
- There is no loading in progress.public static boolean prefetch(java.lang.String path, byte priority)
path
- the absolute pathname of the object to pre-fetch.priority
- the relative priority of this pre-fetch request (higher = more important)
public static boolean prefetch(DSMCCObject dir, java.lang.String path, byte priority)
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)
public void unload() throws NotLoadedException
NotLoadedException
- the carousel object is not loaded.public java.net.URL getURL()
public void addObjectChangeEventListener(ObjectChangeEventListener listener) throws InsufficientResourcesException
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.
listener
- the ObjectChangeEventListener to be notified .
InsufficientResourcesException
- if there are not sufficient resources to
monitor the object for changes.public void removeObjectChangeEventListener(ObjectChangeEventListener listener)
listener
- a previously registered ObjectChangeEventListener.public void loadDirectoryEntry(AsynchronousLoadingEventListener l) throws InvalidPathNameException
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.
l
- a listener which will be called when the loading is done.
InvalidPathNameException
- if the object cannot be found.public void setRetrievalMode(int retrieval_mode)
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.
retrieval_mode
- the retrieval mode to be used for the object
specified as one of the public static final constants in this class.
java.lang.IllegalArgumentException
- if the retrieval_mode specified is not
one listed defined for use with this method.public java.security.cert.X509Certificate[][] getSigners()
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.
public java.security.cert.X509Certificate[][] getSigners(boolean known_root) throws InvalidFormatException, java.io.InterruptedIOException, MPEGDeliveryException, ServerDeliveryException, InvalidPathNameException, NotEntitledException, ServiceXFRException, InsufficientResourcesException
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.
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.
java.io.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
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |