javax.microedition.broadcast.connection
Interface BroadcastFileConnection

All Superinterfaces:

BroadcastConnection, javax.microedition.io.Connection, javax.microedition.io.InputConnection

public interface BroadcastFileConnection
extends BroadcastConnection, javax.microedition.io.InputConnection

BroadcastFileConnection abstracts a broadcast connection as a file or a directory of files. It extends the javax.microedition.io.InputConnection interface of the Generic Connection Framework to provide a standard I/O interface that behaves similar to a FileConnection.

BroadcastFileConnections are read-only. In some broadcast implementation, the content of the connections may be updated by the system in runtime. A BroadcastConnectionListener can be registered to listen for any changes to the connection. Directories will not cause events to be sent to BroadcastConnectionListener.

Files are referenced by URLs. URLs are formed like specified in IETF RFCs 1738 and 2396. Exact formation of the URL is implementation and broadcast specification specific. It's possible that URLs broadcast files have the same syntax and scheme as file URLs in JSR 75 FileConnection API. In that case, methods getURL(), getPath() and getName() function as specified in JSR 75.

In JSR 75 the URL for a file is file://<host>/<root>/<directory>/<filename.extension> (where .extension) is optional and file://<host>/<root>/<directory>/<directoryname>/ for a directory. getURL() obviously returns the whole URL. getName() returns <filename> with possible .extension, or <directoryname> and getPath() returns /root/directory/.

Implementations may cache the broadcast files. System property javax.microedition.broadcast.supports.filecache tells whether the implementation does that or not. The details about how and which files are cached are implementation specific if caching is supported at all. For implementations not doing caching the application can store files considered important into the normal file system of the implementing device.

See broadcast connection examples for some usage examples.

Method Summary

long	directorySize(boolean includeSubDirs) Determines the size in bytes on a file system of all the available files (isAvailable() returns true) that are contained in a directory.
long	fileSize() Determines the size of a file on the file system.
java.lang.String	getName() Returns the name of a file or directory excluding the URL scheme and all paths.
java.lang.String	getPath() Returns the path name excluding the URL scheme, the name of the file or directory and the host from where the file or directory is opened.
java.lang.String	getURL() Returns the URL of the file including the the URL scheme, path and the file name.
boolean	isDirectory() Checks if the object is a directory.
long	lastModified() Returns the time that the file is last modified.
java.util.Enumeration	list() Get a list of BroadcastFileConnections for all visible files and directories contained in a directory.
java.util.Enumeration	list(java.lang.String filter) Get a list of BroadcastFileConnections for all visible files and directories contained in a directory that match the given filter.
java.io.DataInputStream	openDataInputStream() Open and return a data input stream for a connection.
java.io.InputStream	openInputStream() Open and return an input stream for a connection.

Methods inherited from interface javax.microedition.broadcast.connection.BroadcastConnection

addListener, getMimeType, getProperties, isAvailable, removeListener

Methods inherited from interface javax.microedition.io.Connection

close

Method Detail

directorySize

long directorySize(boolean includeSubDirs)
                   throws java.io.IOException

Determines the size in bytes on a file system of all the available files (isAvailable() returns true) that are contained in a directory.

Returns:

size of the directory in bytes.

Throws:

java.io.IOException - if this is not a directory or the directory is unavailable

fileSize

long fileSize()
              throws java.io.IOException

Determines the size of a file on the file system.

Returns:

the size of the file in bytes.

Throws:

java.io.IOException - if this is a directory or the file is unavailable

getName

java.lang.String getName()

Returns the name of a file or directory excluding the URL scheme and all paths. Directory name contains the trailing "/" character.

Returns:

name of the file or the directory.

getPath

java.lang.String getPath()

Returns the path name excluding the URL scheme, the name of the file or directory and the host from where the file or directory is opened.

Returns:

the path.

getURL

java.lang.String getURL()

Returns the URL of the file including the the URL scheme, path and the file name.

Returns:

the URL of the file.

isDirectory

boolean isDirectory()
                    throws java.io.IOException

Checks if the object is a directory.

Returns:

true if object is a directory, false otherwise.

Throws:

java.io.IOException - if the file or the directory is unavailable.

lastModified

long lastModified()
                  throws java.io.IOException

Returns the time that the file is last modified.

Returns:

the time the file is last modified, measured in milliseconds since epoch (00:00:00 GMT, January 1 1970)

Throws:

java.io.IOException - if this is a directory or the file is unavailable

list

java.util.Enumeration list()
                           throws java.io.IOException

Get a list of BroadcastFileConnections for all visible files and directories contained in a directory. Only files known will be listed. I.e. if a file carousel transmits a list of files these should be listed. However, if a file becomes known at the moment its transmission starts it becomes known to the client. Applications need to add a listener to a directory to be notified of newly transmitted files if they are not known in advance.

Returns:

list of BroadcastFileConnections to all visible files and directories in a directory.

Throws:

java.io.IOException - if this is a file and not a directory or if the directory is not available.

list

java.util.Enumeration list(java.lang.String filter)
                           throws java.io.IOException

Get a list of BroadcastFileConnections for all visible files and directories contained in a directory that match the given filter. Only files known will be listed. I.e. if a file carousel transmits a list of files these should be listed. However, if a file becomes known at the moment its transmission starts it becomes known to the client. Applications need to add a listener to a directory to be notified of newly transmitted files if they are not known in advance.

Parameters:

filter - String against which all files and directories are matched for retrieval. An asterisk ("*") can be used as a wildcard to represent 0 or more occurrences of any character.

Returns:

list of BroadcastFileConnections to all visible files and directories in a directory that match the give filter.

Throws:

java.io.IOException - if this is a file and not a directory or if the directory is not available.

java.lang.NullPointerException - if filter is null

java.lang.IllegalArgumentException - if filter contains path specifications, or is an invalid file name (e.g. contains invalid characters, empty String etc.)

openDataInputStream

java.io.DataInputStream openDataInputStream()
                                            throws java.io.IOException

Open and return a data input stream for a connection. If the file is not available an IOEXception will be thrown

Specified by:

openDataInputStream in interface javax.microedition.io.InputConnection

Returns:

DataInputStream to the connection.

Throws:

java.io.IOException - if the stream cannot be opened

java.lang.IllegalArgumentException - if the connection is referring to a directory

openInputStream

java.io.InputStream openInputStream()
                                    throws java.io.IOException

Open and return an input stream for a connection. If the file is not available an IOEXception will be thrown. If the connection is referring to a directory, an IllegalArgumentException will be thrown.

Specified by:

openInputStream in interface javax.microedition.io.InputConnection

Returns:

InputStream to the connection.

Throws:

java.io.IOException - if the stream cannot be opened

java.lang.IllegalArgumentException - if the connection is referring to a directory