com.sun.dtv.broadcast
Class BroadcastFile

java.lang.Object
  java.io.File
      com.sun.dtv.broadcast.BroadcastFile

All Implemented Interfaces:

Serializable, Comparable

public class BroadcastFile
extends File

The BroadcastFile class represents file or directory data obtained from broadcast file systems. If authentication information is provided in the filesystem, the file contents are authenticated before being made available to the application. If authentication fails, it MUST appear to the application that the file does not exist.

An instance of BroadcastFile may be constructed from a Locator instance or via constructors similar to those of java.io.File. This also means that all these constructors use the same characters for name and path separation as other files. On the other hand the locator based constructor uses locators possibly created from URLs following the usual URL based schema where path names are separated by '/'.

Application classes implementing the BroadcastFileListener interface may subscribe with the BroadcastFile to receive notification of changes to the file in the broadcast. Upon the occurrence of a change, the BroadcastFile notifies subscribed BroadcastFileListener instances via BroadcastFileChangeEvent objects.

Successful instantiation of a BroadcastFile object causes its broadcast filesystem to be dynamically "mounted" in the local filesystem. The precise mount point can be determined by calling getBroadcastFilesystem(). It should be noted that a broadcast filesystem can also be explicitly mounted using instances of BroadcastFilesystem.

Construction of a BroadcastFile object causes its contents to be loaded asynchronously (cached) from the broadcast stream. Subsequent attempts to read the data of a BroadcastFile object will block until its contents are loaded. That also means that information about the file (e.g. length) may not be accurate until isCached() returns true. Any write operation will throw an java.io.IOException since broadcast files are read-only and can only be updated via the broadcast channel.

After completely loading a file to the system cache all subsequent input and output operations will work on the loaded file. That means that any updates will not appear in these operations. Updates can be explicitly requested by refreshCache().

Whenever a BroadcastFile is initially loaded or updated in the local cache from the broadcast channel the lastModified information will be updated to the time when it was loaded from the broadcast channel.

Loss of a broadcast file transmission will result in all files already completely in cache being still accessible. Any operations blocked on load operations will throw an IOException as well as construction or new load of files.

All constructors and subsequent input or output operations must use BroadcastException in case they need to throw broadcast specific exceptions.

Broadcast file systems for which there are no remaining BroadcastFile instances or open file descriptors are eligible for unloading from the cache. Broadcast file system for which there are no remaining BroadcastFile instances or open file descriptors are eligible for unmounting from the local filesystem.

Java DTV API implementations that do not support broadcast filesystem access will throw UnsupportedOperationException upon any attempt to construct a BroadcastFile object.

See Also:

Serialized Form

Field Summary

Fields inherited from class java.io.File

pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

BroadcastFile(File dir, String name)
Creates a BroadcastFile instance that represents the file with the specified name in the specified broadcast directory.

BroadcastFile(Locator locator)
Creates a BroadcastFile instance that represents the file referenced by the given Locator.

BroadcastFile(String path)
Creates a BroadcastFile instance that represents the file whose path name in the broadcast is the given path argument.

BroadcastFile(String path, String name)
Creates a BroadcastFile instance that represents the file with the specified name in the specified broadcast directory.

Method Summary

void	addListener(BroadcastFileListener listener) Subscribes a BroadcastFileListener to receive notifications of changes to this BroadcastFile.
BroadcastFilesystem	getBroadcastFilesystem() Returns the BroadcastFileSystem this BroadcastFile belongs to.
Locator	getLocator() Returns a Locator identifying this BroadcastFile.
String	getType() Retrieve the mime type of a BroadcastFile.
boolean	isCached() Retrieve whether or not a BroadcastFile is completely available in filesystem cache locally in the system.
String[]	listDirectory() Lists the directory contents of this BroadcastFile object.
void	refreshCache() Requests that the cached contents of this BroadcastFile be updated with the version currently in the broadcast stream.
void	removeListener(BroadcastFileListener listener) Unsubscribes a BroadcastFileListener from receiving notifications of changes to this BroadcastFile.

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

Constructor Detail

BroadcastFile

public BroadcastFile(Locator locator)
              throws InvalidLocatorException,
                     IOException

Creates a BroadcastFile instance that represents the file referenced by the given Locator. This method does not initiate to load or block on loading files from the broadcast.

This constructor throws java.io.IOException if it determines immediately that the requested broadcast file cannot be accessed. Since this constructor may complete its work asynchronously, absence of an IOException is not a guarantee that the requested broadcast file is accessible.

Parameters:

locator - A Locator referencing the source of the BroadcastFile.

Throws:

InvalidLocatorException - If locator does not refer to a broadcast file.

IOException - If the requested broadcast file cannot be accessed or the received data is invalid.

UnsupportedOperationException - If broadcast filesystem is not supported.

BroadcastFile

public BroadcastFile(String path)
              throws IOException

Creates a BroadcastFile instance that represents the file whose path name in the broadcast is the given path argument.

This constructor throws java.io.IOException if it determines immediately that the requested broadcast file cannot be accessed. Since this constructor may complete its work asynchronously, absence of an IOException is not a guarantee that the requested broadcast file is accessible.

Parameters:

path - The file path name.

Throws:

IOException - If the requested broadcast file cannot be accessed or the received data is invalid.

UnsupportedOperationException - If broadcast filesystem is not supported.

BroadcastFile

public BroadcastFile(File dir,
                     String name)
              throws IOException

Creates a BroadcastFile instance that represents the file with the specified name in the specified broadcast directory.

This constructor throws java.io.IOException if it determines immediately that the requested broadcast file cannot be accessed. Since this constructor may complete its work asynchronously, absence of an IOException is not a guarantee that the requested broadcast file is accessible.

Parameters:

dir - The directory.

name - The file name.

Throws:

IOException - If the requested broadcast file cannot be accessed or the received data is invalid.

UnsupportedOperationException - If broadcast filesystem is not supported.

BroadcastFile

public BroadcastFile(String path,
                     String name)
              throws IOException

Creates a BroadcastFile instance that represents the file with the specified name in the specified broadcast directory.

This constructor throws java.io.IOException if it determines immediately that the requested broadcast file cannot be accessed. Since this constructor may complete its work asynchronously, absence of an IOException is not a guarantee that the requested broadcast file is accessible.

Parameters:

path - The directory path name.

name - The file name.

Throws:

IOException - If the requested broadcast file cannot be accessed or the received data is invalid.

UnsupportedOperationException - If broadcast filesystem is not supported.

Method Detail

listDirectory

public String[] listDirectory()
                       throws IOException

Lists the directory contents of this BroadcastFile object. This list does not include the current or parent directories. This list may also be incomplete in case not all entries in this directory have been loaded yet.

Returns:

An array of file names contained in the directory specified by this BroadcastFile object. If this BroadcastFile object does not refer to a directory, this method returns null.

Throws:

IOException - If the directory cannot be accessed or the received data is invalid.

SecurityException - If a security manager exists and its SecurityManager.checkRead(String) method denies read access to the file.

addListener

public void addListener(BroadcastFileListener listener)
                 throws IOException

Subscribes a BroadcastFileListener to receive notifications of changes to this BroadcastFile. If the specified listener is currently subscribed then no action is performed.

Parameters:

listener - The BroadcastFileListener to be notified.

Throws:

IOException - If there are insufficient resources to support this listener.

SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file.

See Also:

removeListener(com.sun.dtv.broadcast.BroadcastFileListener)

removeListener

public void removeListener(BroadcastFileListener listener)

Unsubscribes a BroadcastFileListener from receiving notifications of changes to this BroadcastFile. If the given BroadcastFileListener is not currently subscribed for notification then no action is performed.

Parameters:

listener - A currently registered BroadcastFileListener.

See Also:

addListener(com.sun.dtv.broadcast.BroadcastFileListener)

getBroadcastFilesystem

public BroadcastFilesystem getBroadcastFilesystem()

Returns the BroadcastFileSystem this BroadcastFile belongs to.

Returns:

A BroadcastFilesystem this BroadcastFile belongs to.

getLocator

public Locator getLocator()

Returns a Locator identifying this BroadcastFile.

Returns:

A Locator identifying this BroadcastFile.

isCached

public boolean isCached()

Retrieve whether or not a BroadcastFile is completely available in filesystem cache locally in the system.

Returns:

true if the BroadcastFile is available in filesystem cache

getType

public String getType()

Retrieve the mime type of a BroadcastFile.

Returns:

the mime type of the BroadcastFile, null if not available.

refreshCache

public void refreshCache()
                  throws SecurityException

Requests that the cached contents of this BroadcastFile be updated with the version currently in the broadcast stream. If the BroadcastFile data does not currently reside in the broadcast stream, subsequent attempts to access its contents will fail.

Throws:

SecurityException - If a security manager exists and its SecurityManager.checkRead(java.lang.String) method denies read access to the file.