Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD