jcontrol.io
Class Resource

java.lang.Object
  jcontrol.io.Resource

All Implemented Interfaces:

ConsoleInputStream, BasicInputStream

public final class Resource
extends Object
implements BasicInputStream, ConsoleInputStream

Implements ROM (and Flash EEPROM) resource read access for JControl. JControls read only memories are organised primary by banks (internal ROM, and one of external flash memory) and secondary by archives. All archives of these banks are merged to a flat structure, there are no directories (the path marker '/' is part of the resource-name).

Resource combines parts of classes typically known as File and FileInputStream for memory reasons. The use of this class can be simple for opening a single resource by name and reading the resource and quite complex for browsing the contents of archives, for example:

 try{
 // opening a single Resource
   Resource r=new Resource("readme.txt");
   String s=r.readLine();     // contents of the first line inside "readme.txt"
   [...]
 
 // listing all Resources in the first archive of the flash memory
   r=new Resource(FLASHACCESS);
   Resource bak=r;            // second reference
   while(r!=null){
     s=r.getName();           // name of the Resource
     [...]
     r=r.next();              // opens the next Resource
   }
 
   r=bak.nextArchive();
   s=r.getName();             // name of the first Resource of the second archive
 } catch(IOException ioe) {}
 

Resources are also used by other parts of the JControl API, e.g. in Display Resources are used to get access to bitmap graphics and fonts.
Note: has to be declared final because of native code usage.

Field Summary

static int	FLASHACCESS Constructor parameter for access to the external flash memory.
static int	ROMACCESS Constructor parameter for access to the internal ROM.

Fields inherited from interface jcontrol.comm.ConsoleInputStream

LF_CHARS

Constructor Summary

Resource(int access)
Constructs access to the first resource in the first archive of the requested bank.

Resource(String name)
Constructs access to a namely known resource.

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.
void	close() Closes the resource, further reads are not possible.
String	getName() Returns the name of the current resource.
int	length() Returns the length of the current resource.
void	mark(int readlimit) NOTE: not supported!
boolean	markSupported() NOTE: not supported!
Resource	next() Returns itself but now accessing the next resource in the current archive or null if there is no further resource or if the archive is protected from listing.
Resource	nextArchive() Returns always null, because we don't known multiple archives in 1 rom-filesystem.
int	read() Reads a single byte from the resource.
int	read(byte[] b) Reads some number of bytes from the input stream and stores them into the buffer array b.
int	read(byte[] buffer, int startindex, int length) Reads to a byte array from the resource.
String	readLine() Reads a single String from the resource.
void	reset() NOTE: not supported!
int	seek(int offset, boolean absolute) Sets the read-pointer of this Resource to a new position.
int	skip(int n) Skips over and discards n bytes of data from this input stream.

Methods inherited from class java.lang.Object

clone, equals, getClass, notifyAll, toString, wait

Field Detail

ROMACCESS

public static final int ROMACCESS

Constructor parameter for access to the internal ROM.

See Also:

Constant Field Values

FLASHACCESS

public static final int FLASHACCESS

Constructor parameter for access to the external flash memory.

See Also:

Constant Field Values

Constructor Detail

Resource

public Resource(String name)
         throws IOException

Constructs access to a namely known resource. All archives in all accessible memory banks are searched in the order also used by the JControl virtual machine. On success the resource can be accessed by any read() method.

Parameters:

name - the resource to search

Throws:

IOException - if the named resource ist not found

Resource

public Resource(int access)
         throws IOException

Constructs access to the first resource in the first archive of the requested bank. Some JControl devices are supporting more than one external flash bank. Resource is only for accessing the default flash bank (the bank the application is running from), for access to other banks use Flash.

Parameters:

access - to get access to internal ROM or external flash memory

Throws:

IOException - if there is no resource in the bank (or the bank is protected from reading)

See Also:

ROMACCESS, FLASHACCESS

Method Detail

next

public Resource next()

Returns itself but now accessing the next resource in the current archive or null if there is no further resource or if the archive is protected from listing. Use this to search resources.

Returns:

itself or null

See Also:

nextArchive(), getName()

nextArchive

public Resource nextArchive()

Returns always null, because we don't known multiple archives in 1 rom-filesystem.

Returns:

always null

getName

public String getName()

Returns the name of the current resource.

Returns:

the name

length

public int length()

Returns the length of the current resource.

Returns:

the length

read

public int read()
         throws IOException

Reads a single byte from the resource.

Specified by:

read in interface BasicInputStream

Returns:

the byte read, converted to a char (range 0 .. 255) or -1 if end of stream is reached

Throws:

IOException

read

public int read(byte[] buffer,
                int startindex,
                int length)
         throws IOException

Reads to a byte array from the resource. The byte array may be partially filled.

Specified by:

read in interface BasicInputStream

Parameters:

buffer - the buffer to fill

startindex - the index to start filling the array

length - number of bytes to read; the array is filled from startindex to startindex+length-1

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 the read is past resouce end

See Also:

InputStream.read()

read

public int read(byte[] b)
         throws IOException

Description copied from interface: BasicInputStream

Reads some number of bytes from the input stream and stores them into the buffer array b. The number of bytes actually read is returned as an integer. This method blocks until input data is available, end of file is detected, or an exception is thrown.

If b is null, a NullPointerException is thrown. If the length of b is zero, then no bytes are read and 0 is returned; otherwise, there is an attempt to read at least one byte. If no byte is available because the stream is at end of file, the value -1 is returned; otherwise, at least one byte is read and stored into b.

The first byte read is stored into element b[0], the next one into b[1], and so on. The number of bytes read is, at most, equal to the length of b. Let k be the number of bytes actually read; these bytes will be stored in elements b[0] through b[k-1], leaving elements b[k] through b[b.length-1] unaffected.

If the first byte cannot be read for any reason other than end of file, then an IOException is thrown. In particular, an IOException is thrown if the input stream has been closed.

The read(b) method for class InputStream has the same effect as:

 read(b, 0, b.length) 

Specified by:

read in interface BasicInputStream

Parameters:

b - the buffer into which the data is read.

Returns:

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

Throws:

IOException - if an I/O error occurs.

See Also:

InputStream.read(byte[], int, int)

close

public void close()

Closes the resource, further reads are not possible. A call of close() isn't nessecary for cleanup. After close() it's still possible to use any file and archive access methods except for reading.

Specified by:

close in interface BasicInputStream

readLine

public String readLine()
                throws IOException

Reads a single String from the resource. The String is received character-by-character until an linefeed character defined in ConsoleInputStream is received. There is a buffer if size BUFFERSIZE allocated to store the received bytes, if the buffer is full a linefeed is forced.

Specified by:

readLine in interface ConsoleInputStream

Returns:

the String read

Throws:

IOException - if an error occurs

See Also:

String

seek

public int seek(int offset,
                boolean absolute)
         throws IOException

Sets the read-pointer of this Resource to a new position.

Parameters:

offset - the new position

absolute - if set offset is relative to begin of FILE otherwise relative to the current read-pointer position

Returns:

the new (absolute) read-pointer

Throws:

IOException - if the new position is out of range

available

public int available()
              throws IOException

Description copied from interface: BasicInputStream

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 or another thread.

Specified by:

available in interface BasicInputStream

Returns:

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

Throws:

IOException - if an I/O error occurs.

skip

public int skip(int n)
         throws IOException

Description copied from interface: BasicInputStream

Skips over and discards n bytes of data from this input stream. The skip method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly 0. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. The actual number of bytes skipped is returned. If n is negative, no bytes are skipped.

The skip method of InputStream creates a byte array and then repeatedly reads into it until n bytes have been read or the end of the stream has been reached. Subclasses are encouraged to provide a more efficient implementation of this method.

Specified by:

skip in interface BasicInputStream

Parameters:

n - the number of bytes to be skipped.

Returns:

the actual number of bytes skipped.

Throws:

IOException - if an I/O error occurs.

mark

public void mark(int readlimit)

NOTE: not supported!

Specified by:

mark in interface BasicInputStream

Parameters:

readlimit - the maximum limit of bytes that can be read before the mark position becomes invalid.

markSupported

public boolean markSupported()

NOTE: not supported!

Specified by:

markSupported in interface BasicInputStream

Returns:

true if this stream instance supports the mark and reset methods; false otherwise.

reset

public void reset()
           throws IOException

NOTE: not supported!

Specified by:

reset in interface BasicInputStream

Throws:

IOException - if this stream has not been makred or if the mark has been invalidated.