javax.microedition.io.file
Interface FileConnection

All Superinterfaces:

Connection, InputConnection, OutputConnection, StreamConnection

public interface FileConnection

extends StreamConnection

[Description] This interface defines the capabilities that a file connection must have.

MOTOROLA and the Stylized M Logo are registered trademarks of Motorola, Inc. Reg. U.S. Pat. & Tm. Off.
© Copyright 2004 Motorola, Inc. All Rights Reserved.

See Also:

Method Summary

long	availableSize() This method determines the free memory that is available on the file system the file or directory resides on Method/constructor extra info
boolean	canRead() Checks if the file or directory is readable.
boolean	canWrite() Checks if the file or directory is writeable.
void	create() Creates a file corresponding to the file string provided in the Connector.open() method for this FileConnection.
void	delete() Deletes the file or directory specified in the Connector.open() URL.
long	directorySize(boolean includeSubDirs) Determines the size in bytes on a file system of all of the files that contained in a directory Method/constructor extra info
boolean	exists() Checks if the file or directory specified in the URL passed to the Connector.open() method exists.
long	fileSize() Determines the size of a file.
String	getName() Returns the name of a file or directory excluding the URL schema and all paths.
String	getPath() Returns the path excluding the file or directory name and the "file" URL schema and host from where the file or directory specified in the Connector.open() method is opened. getName() can be appended to this value to get a fully qualified path filename.
String	getURL() Returns the full file URL including the scheme, host, and path from where the file or directory specified in the Connector.open() method is opened.
boolean	isDirectory() Checks if the URL passed to the Connector.open() is a directory.
boolean	isHidden() Checks if the file is hidden.
boolean	isOpen() Checks if the file is hidden.
long	lastModified() Returns the time that the file denoted by the URL specified in the Connector.open() method was last modified.
Enumeration	list() Gets a list of all files and directories contained in a directory.
Enumeration	list(String filter, boolean includeHidden) Gets a filtered list of files and directories contained in a directory.
void	mkdir() Creates a directory corresponding to the directory string provided in the Connector.open() method.
DataInputStream	openDataInputStream() Open and return a data input stream for a connection.
DataOutputStream	openDataOutputStream() Open and return a data output stream for a connection.
InputStream	openInputStream() Open and return an input stream for a connection.
OutputStream	openOutputStream() Open and return an output stream for a connection.
OutputStream	openOutputStream(long byteOffset) opens an output stream and positions it at the indicated byte offset in the file.
void	rename(String newName) Renames the selected file or directory to a new name in the same directory.
void	setFileConnection(String fileName) Resets this FileConnection object to another file or directory.
void	setHidden(boolean hidden) Sets the hidden attribute of the selected file to the value provided.
void	setReadable(boolean readable) Sets the file or directory readable attribute to the indicated value.
void	setWritable(boolean writable) Sets the selected file or directory writable attribute to the indicated value.
long	totalSize() Determines the total size of the file system the connection's target resides on.
void	truncate(long byteOffset) Truncates the file, discarding all data from the given byte offset to the current end of the file.
long	usedSize() Determines the used memory of a file system the connection's target resides on.

Methods inherited from interface javax.microedition.io.Connection

close

Method Detail

availableSize

public long availableSize()

This method determines the free memory that is available on the file system the file or directory resides on

Method/constructor extra info

Parameters:

return - - long the available size in bytes on a file system.

Throws:

SecurityException - - if the security of the application does not have read access to the root volume.

IllegalStateException - - if the application does have read access to the directory but has opened the connection in Connector.WRITE mode.

See Also:

canRead

public boolean canRead()

Checks if the file or directory is readable.

Method/constructor extra info

Parameters:

return - - true if the connection's target is readable otherwise false. If the connection is closed, false is returned.

Throws:

SecurityException - - if the security of the application does not have read access for the connection's target.

IllegalStateException - - if the application does have read access to the directory but has opened the connection in Connector.WRITE mode.

See Also:

canWrite

public boolean canWrite()

Checks if the file or directory is writeable.

Method/constructor extra info

Parameters:

return - - true if the connection's target is writeable otherwise false. If the connection is closed, false is returned.

Throws:

SecurityException - - if the security of the application does not have read access for the connection's target.

IllegalStateException - - if the application does have read access to the directory but has opened the connection in Connector.WRITE mode.

See Also:

create

public void create()
            throws IOException

Creates a file corresponding to the file string provided in the Connector.open() method for this FileConnection.

Method/constructor extra info

Parameters:

return - - true if the file has been successfully created otherwise false.

Throws:

SecurityException - - if the security of the application does not have write access for the file.

IllegalStateException - - if the application does have write access to the file but has opened the connection in Connector.READ mode.

IOException - - if invoked on an existing file or on any directory (mkdir() is used to create directories), or the connection is closed.

See Also:

delete

public void delete()
            throws IOException

Deletes the file or directory specified in the Connector.open() URL.

Method/constructor extra info

Parameters:

return - - true if the file has been successfully deleted otherwise false.

Throws:

SecurityException - - if the security of the application does not have write access for the file.

IllegalStateException - - if the application does have write access to the file but has opened the connection in Connector.READ mode.

IOException - - if the connection is closed

See Also:

directorySize

public long directorySize(boolean includeSubDirs)
                   throws IOException

Determines the size in bytes on a file system of all of the files that contained in a directory

Method/constructor extra info

Parameters:

return - - long the size in bytes occupied by the files included in the directory. If the connection is closed, the last known value is returned.

inlcudeSubdirs - - boolean if includes subdirctorys

Throws:

SecurityException - - if the security of the application does not have read access for the directory.

IllegalStateException - - if the security of the application does not have read access for the directory.

IOException - - if the method is invoked on a file.

See Also:

exists

public boolean exists()

Checks if the file or directory specified in the URL passed to the Connector.open() method exists.

Method/constructor extra info

Parameters:

return - - true if the specified file/dir exists otherwise false. If the connection is closed, the last known value is returned

Throws:

SecurityException - - if the security of the application does not have read access for the connection's target.

IllegalStateException - - if the application does have read access to the connection's target but has opened the connection in Connector.WRITE mode.

See Also:

fileSize

public long fileSize()
              throws IOException

Determines the size of a file.

Method/constructor extra info

Parameters:

return - - long The size in bytes of the selected file. If the connection is closed, the last known value is returned.

Throws:

IOException - - if the method is invoked on a directory.

SecurityException - - if the security of the application does not have read access for the file.

IllegalStateException - - if the application does have read access to the file but has opened the connection in Connector.WRITE mode.

See Also:

getName

public String getName()

Returns the name of a file or directory excluding the URL schema and all paths.

Method/constructor extra info

Parameters:

return - - String Returns the name of a file or directory excluding the URL schema and all paths.

See Also:

getPath

public String getPath()

Returns the path excluding the file or directory name and the "file" URL schema and host from where the file or directory specified in the Connector.open() method is opened. getName() can be appended to this value to get a fully qualified path filename. The String resulting from this method looks as follows: ///

Method/constructor extra info

Parameters:

return - - String the path of a file or directory

See Also:

getURL

public String getURL()

Returns the full file URL including the scheme, host, and path from where the file or directory specified in the Connector.open() method is opened.

Method/constructor extra info

Parameters:

return - - String the path of a file or directory

See Also:

isDirectory

public boolean isDirectory()

Checks if the URL passed to the Connector.open() is a directory.

Method/constructor extra info

Parameters:

return - - boolean True if the specified URL is a directory otherwise false. If the connection is closed, the last known value is returned.

See Also:

isHidden

public boolean isHidden()

Checks if the file is hidden.

Method/constructor extra info

Parameters:

return - - boolean true if the file is hidden otherwise false. If the connection is closed, the last know value is returned.

Throws:

SecurityException - - if the security of the application does not have read access for the connection's target.

IllegalStateException - - if the application does have read access to the connection's target but has opened the connection in Connector.WRITE mode.

See Also:

isOpen

public boolean isOpen()

Checks if the file is hidden.

Method/constructor extra info

Parameters:

return - - boolean true if the file connection is open,otherwise false.

See Also:

lastModified

public long lastModified()

Returns the time that the file denoted by the URL specified in the Connector.open() method was last modified.

Method/constructor extra info

Parameters:

return - - long value representing the time the file was last modified, or zero if an I/O error occurs.

Throws:

SecurityException - - if the security of the application does not have read access for the connection's target.

IllegalStateException - - if the application does have read access to the connection's target but has opened the connection in Connector.WRITE mode.

See Also:

list

public Enumeration list()
                 throws IOException

Gets a list of all files and directories contained in a directory.

Method/constructor extra info

Parameters:

return - - Enumeration of strings, denoting the files and directories in the directory.

Throws:

IOException - - if the connection is closed, invoked on a file, or an IO error occurs

SecurityException - - if the security of the application does not have read access for the directory.

IllegalStateException - - if the application does have read access to the directory but has opened the connection in Connector.WRITE mode.

See Also:

list

public Enumeration list(String filter,
                        boolean includeHidden)
                 throws IOException

Gets a filtered list of files and directories contained in a directory.

Method/constructor extra info

Parameters:

return - - Enumeration of strings, denoting the files and directories in the directory.

filter - - String against which all files and directories are matched for retrieval.

includeHiden - - boolean

Throws:

IOException - - if the connection is closed, invoked on a file, or an IO error occurs

SecurityException - - if the security of the application does not have read access for the directory.

IllegalStateException - - if the application does have read access to the directory but has opened the connection in Connector.WRITE mode.

NullPointerException - - if filter is null

See Also:

mkdir

public void mkdir()
           throws IOException

Creates a directory corresponding to the directory string provided in the Connector.open() method.

Method/constructor extra info

Parameters:

return - - true if the directory has been successfully created otherwise false

filter - - String against which all files and directories are matched for retrieval.

includeHiden - - boolean

Throws:

IOException - - if invoked on an existing directory or on any file (create() is used to create files), or the connection is closed

SecurityException - - if the security of the application does not have write access to the directory

IllegalStateException - - if the application does have write access to the directory but has opened the connection in Connector.READ mode.

See Also:

openDataInputStream

public DataInputStream openDataInputStream()
                                    throws IOException

Open and return a data input stream for a connection.

Method/constructor extra info

Specified by:

openDataInputStream in interface InputConnection

Parameters:

return - - An input stream

Throws:

IOException - - If an I/O error occurs, if the method is invoked on a directory, or if the application does have read access to the connection's target but has opened the connection in Connector.WRITE mode.

SecurityException - - If the application is not granted read access to the connection's target

See Also:

openDataOutputStream

public DataOutputStream openDataOutputStream()
                                      throws IOException

Open and return a data output stream for a connection.

Method/constructor extra info

Specified by:

openDataOutputStream in interface OutputConnection

Parameters:

return - - An output stream

Throws:

IOException - - If an I/O error occurs, if the method is invoked on a directory, or if the application does have write access to the connection's target but has opened the connection in Connector.READ mode.

SecurityException - - If the application is not granted write access to the connection's target.

See Also:

openInputStream

public InputStream openInputStream()
                            throws IOException

Open and return an input stream for a connection.

Method/constructor extra info

Specified by:

openInputStream in interface InputConnection

Parameters:

return - - An input stream

Throws:

IOException - - If an I/O error occurs, if the method is invoked on a directory, or if the application does have read access to the connection's target but has opened the connection in Connector.WRITE mode

SecurityException - - If the application is not granted read access to the connection's target

See Also:

openOutputStream

public OutputStream openOutputStream()
                              throws IOException

Open and return an output stream for a connection.

Method/constructor extra info

Specified by:

openOutputStream in interface OutputConnection

Parameters:

return - - An output stream

Throws:

IOException - - If an I/O error occurs, if the method is invoked on a directory, or if the application does have write access to the connection's target but has opened the connection in Connector.READ mode.

SecurityException - - If the application is not granted write access to the connection's target.

See Also:

openOutputStream

public OutputStream openOutputStream(long byteOffset)
                              throws IOException

opens an output stream and positions it at the indicated byte offset in the file.

Method/constructor extra info

Parameters:

return - - An output stream

byteOffset - - int number of bytes to skip over from the beginning of the file when positioning the start of the OutputStream.

Throws:

IOException - - If an I/O error occurs, if the method is invoked on a directory, or if the application does have write access to the connection's target but has opened the connection in Connector.READ mode.

IOException - - if the method is invoked on a directory

SecurityException - - If the application is not granted write access to the connection's target.

IllegalArgumentException - - if byteOffset has a negative value

See Also:

rename

public void rename(String newName)
            throws IOException

Renames the selected file or directory to a new name in the same directory.

Method/constructor extra info

Parameters:

newName - - String the new name of the file or directory..

Throws:

IOException - - if the connection's target does not exist, the connection is closed, or a file or directory already exists by the newName.

SecurityException - - if the security of the application does not have write access to the connection's target.

IllegalArgumentException - - if the application does have write access to the connection's target but has opened the connection in Connector.READ mode.

NullPointerException - - if newName is null.

IllegalArgumentException - - if newName contains any path specification or is an invalild filename for the platform (e.g. contains characters invalid in a filename on the platform).

See Also:

setFileConnection

public void setFileConnection(String fileName)
                       throws IOException

Resets this FileConnection object to another file or directory.

Method/constructor extra info

Parameters:

fileName - - name of the file or directory to which this FileConnection will be reset.

Throws:

NullPointerException - - if fileName is null.

IOException - - if the current FileConnection is opened on a file.

SecurityException - - if the security of the application does not have the security access to the specified file or directory as requested in the Connector.open method invocation that originally opened this FileConncetion.

IllegalArgumentException - - if newName contains any path specification or is an invalild .

NullPointerException - - if newName is null.

IllegalArgumentException - - if newName contains any path specification or is an invalild filename for the platform

See Also:

setHidden

public void setHidden(boolean hidden)
               throws IOException

Sets the hidden attribute of the selected file to the value provided.

Method/constructor extra info

Parameters:

hidden - - Boolean The new state of the hidden flag of the selected file.

Throws:

IOException - - if the connection is closed.

SecurityException - - if the security of the application does not have write access to the connection's target

IllegalStateException - - if the application does have write access to the connection's target but has opened the connection in Connector.READ mode.

See Also:

setReadable

public void setReadable(boolean readable)
                 throws IOException

Sets the file or directory readable attribute to the indicated value.

Method/constructor extra info

Parameters:

readable - - The new state of the readable flag of the selected file.

Throws:

SecurityException - - if the security of the application does not have write access to the connection's target.

IllegalStateException - - if the application does have write access to the connection's target but has opened the connection in Connector.READ mode.

IOException -

See Also:

setWritable

public void setWritable(boolean writable)
                 throws IOException

Sets the selected file or directory writable attribute to the indicated value.

Method/constructor extra info

Parameters:

writable - - Boolean the new state of the writable flag of the selected file.

Throws:

SecurityException - - if the security of the application does not have write access to the connection's target.

IllegalStateException - - if the application does have write access to the connection's target but has opened the connection in Connector.READ mode.

IOException -

See Also:

totalSize

public long totalSize()

Determines the total size of the file system the connection's target resides on.

Method/constructor extra info

Parameters:

Return - - Long the total size of the file system in bytes.

Throws:

SecurityException - - if the security of the application does not have read access to the root volume.

IllegalStateException - - if the application does have read access to the connection's target but has opened the connection in Connector.WRITE mode.

IOException -

See Also:

truncate

public void truncate(long byteOffset)
              throws IOException

Truncates the file, discarding all data from the given byte offset to the current end of the file.

Method/constructor extra info

Parameters:

byteOffset - - int offset into the file from which truncation will occur

Throws:

IOException - - if invoked on a directory, the file does not exist, or the connection is closed.

SecurityException - - if the security of the application does not have write access to the file

IllegalStateException - -if the application does have write access to the file but has opened the connection in Connector.READ mode.

IllegalArgumentException - - if byteOffset is null

See Also:

usedSize

public long usedSize()

Determines the used memory of a file system the connection's target resides on.

Method/constructor extra info

Parameters:

Return - - Long The used size of bytes on a file system.

Throws:

SecurityException - - if the security of the application does not have read access to the root volume.

IllegalStateException - - if the application does have read access to the connection's target but has opened the connection in Connector.WRITE mode.

See Also: