javax.tv.carousel

Class CarouselFile

java.lang.Object

java.io.File

javax.tv.carousel.CarouselFile

All Implemented Interfaces:

Serializable, Comparable

public class CarouselFile
extends File

The CarouselFile class represents file or directory data obtained from broadcast file systems. An instance of CarouselFile may be constructed from a Locator instance or via constructors similar to those of java.io.File.

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

Successful instantiation of a CarouselFile object causes its broadcast filesystem to be dynamically "mounted" in the local filesystem. The precise mount point can be determined by calling getCanonicalPath() on the CarouselFile instance representing the top-level directory of the carousel.

Construction of a CarouselFile object causes its contents to be loaded asynchronously from the broadcast stream. Subsequent attempts to read the data of a CarouselFile object will block until its contents are loaded.

Broadcast file data for which there are no remaining CarouselFile instances or open file descriptors are eligible for unloading from the cache. Broadcast carousels for which there are no remaining CarouselFile instances or open file descriptors are eligible for unmounting from the local filesystem.

Java TV API implementations that do not support broadcast filesystem access will throw IOException upon any attempt to construct a CarouselFile object.

See Also:

File.getCanonicalPath(), Serialized Form

Field Summary

Fields inherited from class java.io.File

pathSeparator, pathSeparatorChar, separator, separatorChar

Constructor Summary

Constructors

Constructor and Description
CarouselFile(CarouselFile dir, String name) Creates a CarouselFile instance that represents the file with the specified name in the specified carousel directory.
CarouselFile(Locator locator) Creates a CarouselFile instance that represents the file referenced by the given Locator.
CarouselFile(String path) Creates a CarouselFile instance that represents the file whose path name in the carousel is the given path argument.
CarouselFile(String path, String name) Creates a CarouselFile instance that represents the file with the specified name in the specified carousel directory.

Method Summary

Methods

Modifier and Type	Method and Description
void	addListener(CarouselFileListener listener) Subscribes a CarouselFileListener to receive notifications of changes to this CarouselFile.
Locator	getLocator() Returns a Locator identifying this CarouselFile.
String[]	listDirectoryContents() Lists the directory contents of this CarouselFile object.
void	refreshCache() Requests that the cached contents of this CarouselFile be updated with the version currently in the broadcast stream.
void	removeListener(CarouselFileListener listener) Unsubscribes a CarouselFileListener from receiving notifications of changes to this CarouselFile.

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

Constructor Detail

CarouselFile

public CarouselFile(Locator locator)
             throws InvalidLocatorException,
                    IOException

Creates a CarouselFile instance that represents the file referenced by the given Locator.

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

Parameters:

locator - A Locator referencing the source of the CarouselFile.

Throws:

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

IOException - If the requested carousel file cannot be accessed.

CarouselFile

public CarouselFile(String path)
             throws IOException

Creates a CarouselFile instance that represents the file whose path name in the carousel is the given path argument.

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

Parameters:

path - The file path name.

Throws:

IOException - If the requested carousel file cannot be accessed.

CarouselFile

public CarouselFile(CarouselFile dir,
            String name)
             throws IOException

Creates a CarouselFile instance that represents the file with the specified name in the specified carousel directory.

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

Parameters:

dir - The directory.

name - The file name.

Throws:

IOException - If the requested carousel file cannot be accessed.

CarouselFile

public CarouselFile(String path,
            String name)
             throws IOException

Creates a CarouselFile instance that represents the file with the specified name in the specified carousel directory.

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

Parameters:

path - The directory path name.

name - The file name.

Throws:

IOException - If the requested carousel file cannot be accessed.

Method Detail

listDirectoryContents

public String[] listDirectoryContents()
                               throws IOException,
                                      SecurityException

Lists the directory contents of this CarouselFile object. This list does not include the current or parent directories.

Returns:

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

Throws:

IOException - If the directory cannot be accessed.

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

addListener

public void addListener(CarouselFileListener listener)
                 throws IOException,
                        SecurityException

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

Parameters:

listener - The CarouselFileListener 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.

removeListener

public void removeListener(CarouselFileListener listener)

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

Parameters:

listener - A currently registered CarouselFileListener.

getLocator

public Locator getLocator()

Returns a Locator identifying this CarouselFile.

Returns:

A Locator identifying this CarouselFile.

refreshCache

public void refreshCache()
                  throws SecurityException

Requests that the cached contents of this CarouselFile be updated with the version currently in the broadcast stream. If the CarouselFile 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.