jcontrol.io
Class Resource

java.lang.Object
  extended by jcontrol.io.Resource
All Implemented Interfaces:
ConsoleInputStream, BasicInputStream, File

public final class Resource
extends Object
implements BasicInputStream, ConsoleInputStream, File

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 archieves. All archives of these banks are merged to a flat structure, there are no directories (the path marker '/' is part of the resource-name). Classes are stored using their package path with the '/' separator but excluding the extension (".class"). Further there in no read access to class files possible!

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 og native code usage.

Author:
Helge Böhme
Available on JControl Devices:
all

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
 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.
 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 itself but now accessing the first resource in the next archive or null if there is no further archive (in the current bank).
 char read()
          Reads a single byte from the resource.
 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.
 int seek(int offset, boolean absolute)
          Sets the read-pointer of this Resource to a new position.
 
Methods inherited from class java.lang.Object
clone, equals, notifyAll, wait
 

Field Detail

FLASHACCESS

public static final int FLASHACCESS
Constructor parameter for access to the external flash memory.

See Also:
Constant Field Values

ROMACCESS

public static final int ROMACCESS
Constructor parameter for access to the internal ROM.

See Also:
Constant Field Values
Constructor Detail

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

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
Method Detail

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

getName

public String getName()
Returns the name of the current resource.

Specified by:
getName in interface File
Returns:
the name

length

public int length()
Returns the length of the current resource.

Specified by:
length in interface File
Returns:
the length

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 itself but now accessing the first resource in the next archive or null if there is no further archive (in the current bank). Use this to search archives.

Returns:
itself or null
See Also:
next(), getName()

read

public char 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)
Throws:
IOException - if the read is past resouce end

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 number of received bytes
Throws:
IOException - if the read is past resouce end

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.

Specified by:
seek in interface File
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