com.sun.squawk.io.j2me.file
Class Protocol

java.lang.Object
  com.sun.squawk.io.ConnectionBase
      com.sun.squawk.io.ConnectionBaseAdapter
          com.sun.squawk.io.j2me.file.Protocol

All Implemented Interfaces:

FileConnection, Connection, InputConnection, OutputConnection, StreamConnection

public class Protocol
extends ConnectionBaseAdapter
implements FileConnection

This class implements the necessary functionality for a File connection. This version extends JSR 75 FileConnections by allowing relative pathnames, and having the host and root sections of the path be optional. The result is that a URI that starts with 3 or 4 slashes is treated as an absolute path, while a URI that starts with two slashes is treated as relative.

Field Summary

Fields inherited from class com.sun.squawk.io.ConnectionBaseAdapter

connectionOpen, iStreams, maxIStreams, maxOStreams, oStreams

Constructor Summary

Protocol()
Constructor for file connection implementation.

Method Summary

int	available() Returns the number of bytes that can be read (or skipped over) from this input stream without blocking by the next caller of a method for this input stream.
protected void	checkReadPermission() Checks that the application has permission to read.
protected void	checkRootReadPermission() Checks that the application has permission to read the root path.
protected void	checkWritePermission() Checks that the application has permission to write.
protected void	closeInputStream() Called once by each child input stream.
protected void	closeOutputStream() Called once by each child output stream.
protected void	connect(String name, int mode, boolean timeouts) Establishes the connection.
void	create()
static void	create(String name) Create a file for writing
void	delete()
protected void	disconnect() Free up the connection resources.
protected void	ensureConnected() Checks that the connection is already open.
protected void	ensureOpenAndConnected() Checks that the connection is already open and connected.
boolean	exists()
static boolean	exists(String name) return true if the specified file exists
long	fileSize()
protected void	flush() Forces any buffered output bytes to be written out.
String	getName()
String	getPath()
String	getURL()
boolean	isDirectory()
boolean	isOpen()
Connection	open(String protocol, String name, int mode, boolean timeouts) Open the 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)
Connection	openPrim(String name, int mode, boolean timeouts) Opens the file connection.
protected int	readBytes(byte[] b, int off, int len) Reads up to len bytes of data from the input stream into an array of bytes, blocks until at least one byte is available.
protected int	writeBytes(byte[] b, int off, int len) Writes len bytes from the specified byte array starting at offset off to this output stream.

Methods inherited from class com.sun.squawk.io.ConnectionBaseAdapter

close, ensureOpen, initStreamConnection, mark, markSupported, notifyClosedInput, notifyClosedOutput, openDataInputStream, openDataOutputStream, reset

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.sun.squawk.microedition.io.FileConnection

openDataInputStream, openDataOutputStream

Methods inherited from interface javax.microedition.io.Connection

close

Constructor Detail

Protocol

public Protocol()

Constructor for file connection implementation.

Method Detail

available

public int available()
              throws IOException

Returns the number of bytes that can be read (or skipped over) from this input stream without blocking by the next caller of a method for this input stream. The next caller might be the same thread or another thread.

Overrides:

available in class ConnectionBaseAdapter

Returns:

the number of bytes that can be read from this input stream without blocking.

Throws:

IOException - if an I/O error occurs.

open

public Connection open(String protocol,
                       String name,
                       int mode,
                       boolean timeouts)
                throws IOException

Open the connection

Specified by:

open in class ConnectionBase

Parameters:

name - the target for the connection. It must be in this format: "//:"

mode - read/write mode of the connection (currently ignored).

timeouts - A flag to indicate that the called wants timeout exceptions (currently ignored).

protocol - The URL protocol

Returns:

new connection

Throws:

IOException

ConnectionNotFoundException - If the connection cannot be found.

openPrim

public Connection openPrim(String name,
                           int mode,
                           boolean timeouts)
                    throws IOException

Opens the file connection.

Specified by:

openPrim in class ConnectionBaseAdapter

Parameters:

name - URL path fragment

mode - access mode

timeouts - flag to indicate that timeouts allowed

Returns:

an opened Connection

Throws:

IOException - if some other kind of I/O error occurs.

isOpen

public boolean isOpen()

Specified by:

isOpen in interface FileConnection

openInputStream

public InputStream openInputStream()
                            throws IOException

Open and return an input stream for a connection. The connection's target must already exist and be accessible for the input stream to be created.

Specified by:

openInputStream in interface FileConnection

Specified by:

openInputStream in interface InputConnection

Overrides:

openInputStream in class ConnectionBaseAdapter

Returns:

An open input stream

Throws:

IOException - if an I/O error occurs, if the method is invoked on a directory, if the connection's target does not yet exist, or the connection's target is not accessible.

IllegalStateException - 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.

openOutputStream

public OutputStream openOutputStream()
                              throws IOException

Open and return an output stream for a connection. The output stream is positioned at the start of the file. Writing data to the output stream overwrites the contents of the files (i.e. does not insert data). Writing data to output streams beyond the current end of file automatically extends the file size. The connection's target must already exist and be accessible for the output stream to be created. openOutputStream(long) should be used to position an output stream to a different position in the file.

Changes made to a file through an output stream may not be immediately made to the actual file residing on the file system because platform and implementation specific use of caching and buffering of the data. Stream contents and file length extensions are not necessarily visible outside of the application immediately unless flush() is called on the stream.? The returned output stream is automatically and synchronously flushed when it is closed.

Specified by:

openOutputStream in interface FileConnection

Specified by:

openOutputStream in interface OutputConnection

Overrides:

openOutputStream in class ConnectionBaseAdapter

Returns:

An open output stream

Throws:

IOException - If an I/O error occurs, if the method is invoked on a directory, the file does not yet exist, or the connection's target is not accessible.

IllegalStateException - 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(long)

openOutputStream

public OutputStream openOutputStream(long byteOffset)
                              throws IOException

Specified by:

openOutputStream in interface FileConnection

Throws:

IOException

fileSize

public long fileSize()
              throws IOException

Specified by:

fileSize in interface FileConnection

Throws:

IOException

create

public void create()
            throws IOException

Specified by:

create in interface FileConnection

Throws:

IOException

exists

public boolean exists()

Specified by:

exists in interface FileConnection

isDirectory

public boolean isDirectory()

Specified by:

isDirectory in interface FileConnection

delete

public void delete()
            throws IOException

Specified by:

delete in interface FileConnection

Throws:

IOException

getName

public String getName()

Specified by:

getName in interface FileConnection

getPath

public String getPath()

Specified by:

getPath in interface FileConnection

getURL

public String getURL()

Specified by:

getURL in interface FileConnection

readBytes

protected int readBytes(byte[] b,
                        int off,
                        int len)
                 throws IOException

Reads up to len bytes of data from the input stream into an array of bytes, blocks until at least one byte is available.

Specified by:

readBytes in class ConnectionBaseAdapter

Parameters:

b - the buffer into which the data is read.

off - the start offset in array b at which the data is written.

len - the maximum number of bytes to read.

Returns:

the total number of bytes read into the buffer, or -1 if there is no more data because the end of the stream has been reached.

Throws:

IOException - if an I/O error occurs.

writeBytes

protected int writeBytes(byte[] b,
                         int off,
                         int len)
                  throws IOException

Writes len bytes from the specified byte array starting at offset off to this output stream.

Polling the native code is done here to allow for simple asynchronous native code to be written. Not all implementations work this way (they block in the native code) but the same Java code works for both.

Specified by:

writeBytes in class ConnectionBaseAdapter

Parameters:

b - the data.

off - the start offset in the data.

len - the number of bytes to write.

Returns:

number of bytes written

Throws:

IOException - if an I/O error occurs. In particular, an IOException is thrown if the output stream is closed.

flush

protected void flush()
              throws IOException

Forces any buffered output bytes to be written out. The general contract of flush is that calling it is an indication that, if any bytes previously written that have been buffered by the connection, should immediately be written to their intended destination.

The flush method of ConnectionBaseAdapter does nothing.

Overrides:

flush in class ConnectionBaseAdapter

Throws:

IOException - if an I/O error occurs.

closeInputStream

protected void closeInputStream()
                         throws IOException

Called once by each child input stream. If the input stream is marked open, it will be marked closed and the if the connection and output stream are closed the disconnect method will be called.

Overrides:

closeInputStream in class ConnectionBaseAdapter

Throws:

IOException - if the subclass throws one

closeOutputStream

protected void closeOutputStream()
                          throws IOException

Called once by each child output stream. If the output stream is marked open, it will be marked closed and the if the connection and input stream are closed the disconnect method will be called.

Overrides:

closeOutputStream in class ConnectionBaseAdapter

Throws:

IOException - if the subclass throws one

disconnect

protected void disconnect()
                   throws IOException

Free up the connection resources.

Specified by:

disconnect in class ConnectionBaseAdapter

Throws:

IOException - if an I/O error occurs.

connect

protected void connect(String name,
                       int mode,
                       boolean timeouts)
                throws IOException

Establishes the connection.

Parameters:

name - URL path fragment

mode - access mode

timeouts - flag to indicate that timeouts allowed

Throws:

IOException - if an error occurs

ensureConnected

protected void ensureConnected()
                        throws IOException

Checks that the connection is already open.

Throws:

IOException - if the connection is closed

exists

public static boolean exists(String name)

return true if the specified file exists

Parameters:

name -

Returns:

create

public static void create(String name)
                   throws IOException

Create a file for writing

Parameters:

name - full pathname to file

Throws:

IOException - if file can't be created

ensureOpenAndConnected

protected void ensureOpenAndConnected()
                               throws IOException

Checks that the connection is already open and connected.

Throws:

ConnectionClosedException - if the connection is closed

IOException - if any error occurs while connecting

checkReadPermission

protected final void checkReadPermission()
                                  throws InterruptedIOException

Checks that the application has permission to read.

Throws:

InterruptedIOException - if the permission dialog is terminated before completed

SecurityException - if read is not allowed

IllegalStateException - if connection is write only

checkRootReadPermission

protected final void checkRootReadPermission()
                                      throws InterruptedIOException

Checks that the application has permission to read the root path.

Throws:

InterruptedIOException - if the permission dialog is terminated before completed

SecurityException - if read is not allowed

IllegalStateException - if connection is write only

checkWritePermission

protected final void checkWritePermission()
                                   throws InterruptedIOException

Checks that the application has permission to write.

Throws:

InterruptedIOException - if the permission dialog is terminated before completed

SecurityException - if write is not allowed

IllegalStateException - if connection is read only