Java TV(tm) API 1.0

javax.tv.carousel
Class CarouselFile

java.lang.Object
  |
  +--java.io.File
        |
        +--javax.tv.carousel.CarouselFile
All Implemented Interfaces:
java.lang.Comparable, java.io.Serializable

public class CarouselFile
extends java.io.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

Fields inherited from class java.io.File
pathSeparator, pathSeparatorChar, separator, separatorChar
 
Constructor Summary
CarouselFile(CarouselFile dir, java.lang.String name)
          Creates a CarouselFile instance that represents the file with the specified name relative to the specified carousel directory.
CarouselFile(Locator locator)
          Creates a CarouselFile instance that represents the file referenced by the given Locator.
CarouselFile(java.lang.String path)
          Creates a CarouselFile instance that represents the file whose absolute path name is the given path argument.
CarouselFile(java.lang.String path, java.lang.String name)
          Creates a CarouselFile instance that represents the file with the specified name relative to the specified carousel directory.
 
Method Summary
 void addListener(CarouselFileListener listener)
          Subscribes a CarouselFileListener to receive notifications of changes to this CarouselFile.
 Locator getLocator()
          Returns a Locator identifying this CarouselFile.
 java.lang.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
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, 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,
                    java.io.IOException
Creates a CarouselFile instance that represents the file referenced by the given Locator. Successful construction of the CarouselFile instance causes the referenced broadcast filesystem to be dynamically mounted in the local filesystem.

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.
java.io.IOException - If the requested carousel file cannot be accessed.

CarouselFile

public CarouselFile(java.lang.String path)
             throws java.io.IOException
Creates a CarouselFile instance that represents the file whose absolute path name 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 absolute path name of the file.
Throws:
java.io.IOException - If the requested carousel file cannot be accessed.

CarouselFile

public CarouselFile(CarouselFile dir,
                    java.lang.String name)
             throws java.io.IOException
Creates a CarouselFile instance that represents the file with the specified name relative to 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 name of the file, relative to dir.
Throws:
java.io.IOException - If the requested carousel file cannot be accessed.

CarouselFile

public CarouselFile(java.lang.String path,
                    java.lang.String name)
             throws java.io.IOException
Creates a CarouselFile instance that represents the file with the specified name relative to 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 absolute directory path name.
name - The name of the file, relative to path.
Throws:
java.io.IOException - If the requested carousel file cannot be accessed.
Method Detail

listDirectoryContents

public java.lang.String[] listDirectoryContents()
                                         throws java.io.IOException,
                                                java.lang.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:
java.io.IOException - If the directory cannot be accessed.
java.lang.SecurityException - If a security manager exists and its java.lang.SecurityManager.checkRead(String) method denies read access to the file.

addListener

public void addListener(CarouselFileListener listener)
                 throws java.io.IOException,
                        java.lang.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:
java.io.IOException - If there are insufficient resources to support this listener.
java.lang.SecurityException - If a security manager exists and its java.lang.SecurityManager.checkRead(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 java.lang.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:
java.lang.SecurityException - If a security manager exists and its java.lang.SecurityManager.checkRead(java.lang.String) method denies read access to the file.

Java TV(tm) API 1.0

Copyright © 1998 - 2000 Sun Microsystems, Inc.