Dallas Semiconductor 1-Wire API 1.00 Alpha: Class OWFileInputStream

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

## com.dalsemi.onewire.utils
Class OWFileInputStream

    java.lang.Object
      |
      +--java.io.InputStream
            |
            +--com.dalsemi.onewire.utils.OWFileInputStream

public class OWFileInputStream
extends InputStream

A `OWFileInputStream` obtains input bytes from a file in a 1-Wire Filesystem. What files are available depends on the 1-Wire device.

Note that the 1-Wire File system can reside across multiple 1-Wire devices. In this case only one of the devices need be supplied to the constructor. Each device in a multi-device file system contains information to reacquire the entire list.

File and directory name limitations

- File/directory names limited to 4 characters not including extension
- File/directory names are not case sensitive and will be automatically changed to all-CAPS
- Only files can have extensions
- Extensions are numberical in the range 0 to 125
- Extensions 100 to 125 are special purpose and not yet implemented or allowed
- Files can have the read-only attribute
- Directories can have the hidden attribute
- It is recommended to limit directory depth to 10 levels to accomodate legacy implementations

### Usage

  #### Example

  Read from a 1-Wire file on device 'owd':

         // get an input stream to the 1-Wire file
         OWFileInputStream instream = new OWFileInputStream(owd, "DEMO.0");

         // read some data
         byte[] data = new byte[2000];
         int len = instream.read(data);

         // close the stream to release system resources
         instream.close();

  Version:
    0.01, 1 June 2001
  See Also:
    `OWFile`, `OWFileDescriptor`, `OWFileOutputStream`

  Constructor Summary
  `OWFileInputStream(OneWireContainer[] owd, String name)` Creates a `FileInputStream` by opening a connection to an actual file, the file named by the path name `name` in the Filesystem.
  `OWFileInputStream(OneWireContainer owd, String name)` Creates a `FileInputStream` by opening a connection to an actual file, the file named by the path name `name` in the Filesystem.
  `OWFileInputStream(OWFile file)` Creates a `OWFileInputStream` by opening a connection to an actual file, the file named by the `File` object `file` in the Filesystem.
  `OWFileInputStream(OWFileDescriptor fdObj)` Creates a `OWFileInputStream` by using the file descriptor `fdObj`, which represents an existing connection to an actual file in the Filesystem.

  Method Summary
  `int` | `available()` Returns the number of bytes that can be read from this file input stream without blocking.
  `void` | `close()` Closes this file input stream and releases any system resources associated with the stream.
  `void` | `finalize()` Ensures that the `close` method of this file input stream is called when there are no more references to it.
  `OWFileDescriptor` | `getFD()` Returns the `OWFileDescriptor` object that represents the connection to the actual file in the Filesystem being used by this `FileInputStream`.
  `void` | `mark(int readlimit)` Marks the current position in this input stream.
  `boolean` | `markSupported()` Tests if this input stream supports the `mark` and `reset` methods.
  `int` | `read()` Reads a byte of data from this input stream.
  `int` | `read(byte[] b)` Reads up to `b.length` bytes of data from this input stream into an array of bytes.
  `int` | `read(byte[] b, int off, int len)` Reads up to `len` bytes of data from this input stream into an array of bytes.
  `void` | `reset()` Repositions this stream to the position at the time the `mark` method was last called on this input stream.
  `long` | `skip(long n)` Skips over and discards `n` bytes of data from the input stream.

  Methods inherited from class java.lang.Object
  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  Constructor Detail

  ### OWFileInputStream

      public OWFileInputStream(OneWireContainer owd,
                               String name)
                        throws FileNotFoundException

    Creates a `FileInputStream` by opening a connection to an actual file, the file named by the path name `name` in the Filesystem. A new `OWFileDescriptor` object is created to represent this file connection.

    First, if there is a security manager, its `checkRead` method is called with the `name` argument as its argument.

    If the named file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading then a `FileNotFoundException` is thrown.

    Parameters:
      `owd` - OneWireContainer that this Filesystem resides on
      `name` - the system-dependent file name.
    Throws:
      `FileNotFoundException` - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.

  ### OWFileInputStream

      public OWFileInputStream(OneWireContainer[] owd,
                               String name)
                        throws FileNotFoundException

    Creates a `FileInputStream` by opening a connection to an actual file, the file named by the path name `name` in the Filesystem. A new `OWFileDescriptor` object is created to represent this file connection.

    First, if there is a security manager, its `checkRead` method is called with the `name` argument as its argument.

    If the named file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading then a `FileNotFoundException` is thrown.

    Parameters:
      `owd` - array of OneWireContainers that this Filesystem resides on
      `name` - the system-dependent file name.
    Throws:
      `FileNotFoundException` - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.

  ### OWFileInputStream

      public OWFileInputStream(OWFile file)
                        throws FileNotFoundException

    Creates a `OWFileInputStream` by opening a connection to an actual file, the file named by the `File` object `file` in the Filesystem. A new `OWFileDescriptor` object is created to represent this file connection.

    If the named file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading then a `FileNotFoundException` is thrown.

    Parameters:
      `file` - the file to be opened for reading.
    Throws:
      `FileNotFoundException` - if the file does not exist, is a directory rather than a regular file, or for some other reason cannot be opened for reading.
    See Also:
      `OWFile.getPath()`

  ### OWFileInputStream

      public OWFileInputStream(OWFileDescriptor fdObj)

    Creates a `OWFileInputStream` by using the file descriptor `fdObj`, which represents an existing connection to an actual file in the Filesystem.

    If `fdObj` is null then a `NullPointerException` is thrown.

    Parameters:
      `fdObj` - the file descriptor to be opened for reading.

  Method Detail

  ### read

      public int read()
               throws IOException

    Reads a byte of data from this input stream. This method blocks if no input is yet available.
    Overrides:
      `read` in class `InputStream`
    Returns:
      the next byte of data, or `-1` if the end of the file is reached.
    Throws:
      `IOException` - if an I/O error occurs.

  ### read

      public int read(byte[] b)
               throws IOException

    Reads up to `b.length` bytes of data from this input stream into an array of bytes. This method blocks until some input is available.
    Overrides:
      `read` in class `InputStream`
    Parameters:
      `b` - the buffer into which the data is read.
    Returns:
      the total number of bytes read into the buffer, or `-1` if there is no more data because the end of the file has been reached.
    Throws:
      `IOException` - if an I/O error occurs.

  ### read

      public int read(byte[] b,
                      int off,
                      int len)
               throws IOException

    Reads up to `len` bytes of data from this input stream into an array of bytes. This method blocks until some input is available.
    Overrides:
      `read` in class `InputStream`
    Parameters:
      `b` - the buffer into which the data is read.
      `off` - the start offset of the data.
      `len` - the maximum number of bytes read.
    Returns:
      the total number of bytes read into the buffer, or `-1` if there is no more data because the end of the file has been reached.
    Throws:
      `IOException` - if an I/O error occurs.

  ### skip

      public long skip(long n)
                throws IOException

    Skips over and discards `n` bytes of data from the input stream. The `skip` method may, for a variety of reasons, end up skipping over some smaller number of bytes, possibly `0`. The actual number of bytes skipped is returned.
    Overrides:
      `skip` in class `InputStream`
    Parameters:
      `n` - the number of bytes to be skipped.
    Returns:
      the actual number of bytes skipped.
    Throws:
      `IOException` - if an I/O error occurs.

  ### available

      public int available()
                    throws IOException

    Returns the number of bytes that can be read from this file input stream without blocking.
    Overrides:
      `available` in class `InputStream`
    Returns:
      the number of bytes that can be read from this file input stream without blocking.
    Throws:
      `IOException` - if an I/O error occurs.

  ### close

      public void close()
                 throws IOException

    Closes this file input stream and releases any system resources associated with the stream.
    Overrides:
      `close` in class `InputStream`
    Throws:
      `IOException` - if an I/O error occurs.

  ### getFD

      public final OWFileDescriptor getFD()
                                   throws IOException

    Returns the `OWFileDescriptor` object that represents the connection to the actual file in the Filesystem being used by this `FileInputStream`.
    Returns:
      the file descriptor object associated with this stream.
    Throws:
      `IOException` - if an I/O error occurs.
    See Also:
      `OWFileDescriptor`

  ### finalize

      public void finalize()
                    throws IOException

    Ensures that the `close` method of this file input stream is called when there are no more references to it.
    Throws:
      `IOException` - if an I/O error occurs.
    See Also:
      `close()`

  ### mark

      public void mark(int readlimit)

    Marks the current position in this input stream. A subsequent call to the `reset` method repositions this stream at the last marked position so that subsequent reads re-read the same bytes.

    The `readlimit` arguments tells this input stream to allow that many bytes to be read before the mark position gets invalidated.

    The general contract of `mark` is that, if the method `markSupported` returns `true`, the stream somehow remembers all the bytes read after the call to `mark` and stands ready to supply those same bytes again if and whenever the method `reset` is called. However, the stream is not required to remember any data at all if more than `readlimit` bytes are read from the stream before `reset` is called.

    The `mark` method of `InputStream` does nothing.

    Overrides:
      `mark` in class `InputStream`
    Parameters:
      `readlimit` - the maximum limit of bytes that can be read before the mark position becomes invalid.
    See Also:
      `InputStream.reset()`

  ### reset

      public void reset()
                 throws IOException

    Repositions this stream to the position at the time the `mark` method was last called on this input stream.

    The general contract of `reset` is:

    - If the method `markSupported` returns `true`, then:
      - If the method `mark` has not been called since the stream was created, or the number of bytes read from the stream since `mark` was last called is larger than the argument to `mark` at that last call, then an `IOException` might be thrown.
      - If such an `IOException` is not thrown, then the stream is reset to a state such that all the bytes read since the most recent call to `mark` (or since the start of the file, if `mark` has not been called) will be resupplied to subsequent callers of the `read` method, followed by any bytes that otherwise would have been the next input data as of the time of the call to `reset`.
    - If the method `markSupported` returns `false`, then:
      - The call to `reset` may throw an `IOException`.
      - If an `IOException` is not thrown, then the stream is reset to a fixed state that depends on the particular type of the input stream and how it was created. The bytes that will be supplied to subsequent callers of the `read` method depend on the particular type of the input stream.

    The method `reset` for class `InputStream` does nothing and always throws an `IOException`.

    Overrides:
      `reset` in class `InputStream`
    Throws:
      `IOException` - if this stream has not been marked or if the mark has been invalidated.
    See Also:
      `InputStream.mark(int)`, `IOException`

  ### markSupported

      public boolean markSupported()

    Tests if this input stream supports the `mark` and `reset` methods. The `markSupported` method of `InputStream` returns `false`.
    Overrides:
      `markSupported` in class `InputStream`
    Returns:
      `true` if this true type supports the mark and reset method; `false` otherwise.
    See Also:
      `InputStream.mark(int)`, `InputStream.reset()`

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