Class OWFileDescriptor

java.lang.Object
com.dalsemi.onewire.application.file.OWFileDescriptor

public class OWFileDescriptor extends Object
Instances of the 1-Wire file descriptor class serve as an opaque handle to the underlying machine-specific structure representing an open file, an open socket, or another source or sink of bytes. The main practical use for a file descriptor is to create a OWFileInputStream or OWFileOutputStream to contain it.

Applications should not create their own file descriptors.

See Also:
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
     
    Construct an invalid 1-Wire FileDescriptor
    protected
    Construct a 1-Wire FileDescrioptor providing the Filesystem 1-Wire device and file path.
    protected
    Construct a 1-Wire FileDescrioptor providing the Filesystem 1-Wire device and file path.
  • Method Summary

    Modifier and Type
    Method
    Description
    protected int
    Returns the number of bytes that can be read from this file input stream without blocking.
    protected boolean
    Checks to see if can read the file associated with this descriptor.
    protected boolean
    Checks to see if the file represented by this descriptor is writable.
    protected void
    Closes this file descriptor and releases any system resources associated with this stream.
    protected void
    create(boolean append, boolean isDirectory, boolean makeParents, int startPage, int numberPages)
    Creates a directory or file to write.
    protected boolean
    Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist.
    protected boolean
    Delete this file or directory represented by this descriptor.
    protected boolean
    Checks to see if the file exists
    protected void
    Format the Filesystem on the 1-Wire device.
    protected void
    Free's this file descriptors system resources.
    protected boolean
    freePage(int page)
    free the specified page as being un-used in the page bitmap
    protected int
    getFirstFreePage(boolean counterPage)
    Get the first free page from the page bitmap.
    protected int
    Gets the number of bytes available on this device for file and directory information.
    protected int
    Computes a hash code for this abstract pathname.
    protected int
    getLocalPage(int page)
    Gets the local page number on the memory bank object for the specified page.
    protected PagedMemoryBank
    Gets the memory bank object for the specified page.
    protected String
    Returns the name of the file or directory denoted by this abstract pathname.
    protected int
    getNextFreePage(boolean counterPage)
    Get the next free page from the page bitmap.
    protected OneWireContainer[]
    Gets the OneWireContainers that represent this Filesystem.
    protected int[]
    Gets an array of integers that represents the page list of the file or directory represented by this OWFile.
    protected String
    Returns the pathname string of this abstract pathname's parent, or null if this pathname does not name a parent directory.
    protected String
    Converts this abstract pathname into a pathname string.
    protected int
    Returns an integer which represents the starting memory page of the file or directory represented by this OWFile.
    protected boolean
    Checks to see if this is a directory.
    protected boolean
    Checks to see if this is a file
    protected boolean
    Checks to see if this directory is hidden.
    protected long
    Get the estimated length of the file represented by this descriptor.
    protected String[]
    Returns an array of strings naming the files and directories in the directory denoted by this abstract pathname.
    protected void
    mark(int readlimit)
    Mark the current position in the file being read for later reference.
    protected void
    markPageUsed(int page)
    Mark the specified page as used in the page bitmap.
    protected void
    Opens the file for reading.
    protected int
    Reads a byte of data from this input stream.
    protected int
    read(byte[] b, int off, int len)
    Reads up to len bytes of data from this input stream into an array of bytes.
    protected void
    Read the page bitmap.
    protected boolean
    Renames the file denoted by this abstract pathname.
    protected void
    Reset the the read of this file back to the marked position.
    protected boolean
    Marks the file or directory named by this abstract pathname so that only read operations are allowed.
    protected void
    setupFD(OneWireContainer[] owd, String newPath)
    Setups the 1-Wire FileDescrioptor providing the Filesystem 1-Wire device(s) and file path.
    protected long
    skip(long n)
    Skips over and discards n bytes of data from the input stream.
    void
    Force all system buffers to synchronize with the underlying device.
    boolean
    Tests if this file descriptor object is valid.
    protected int
    verifyDeviceMap(int startPage, int numberOfContainers, boolean setOverdrive)
    Verify the Device Map of a MASTER device is correct.
    protected void
    write(byte[] b, int off, int len)
    Writes len bytes from the specified byte array starting at offset off to this file output stream.
    protected void
    write(int b)
    Writes the specified byte to this file output stream.
    protected void
    Write the page bitmap back to the device.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • OWFileDescriptor

      public OWFileDescriptor()
      Construct an invalid 1-Wire FileDescriptor
    • OWFileDescriptor

      protected OWFileDescriptor(OneWireContainer owd, String newPath)
      Construct a 1-Wire FileDescrioptor providing the Filesystem 1-Wire device and file path.
      Parameters:
      owd - - 1-Wire container where the filesystem resides
      newPath - - path containing the file/directory that represents this file descriptor
    • OWFileDescriptor

      protected OWFileDescriptor(OneWireContainer[] owd, String newPath)
      Construct a 1-Wire FileDescrioptor providing the Filesystem 1-Wire device and file path.
      Parameters:
      owd - - 1-Wire container where the filesystem resides
      newPath - - path containing the file/directory that represents this file descriptor
  • Method Details

    • setupFD

      protected void setupFD(OneWireContainer[] owd, String newPath)
      Setups the 1-Wire FileDescrioptor providing the Filesystem 1-Wire device(s) and file path.
      Parameters:
      owd - - 1-Wire container where the filesystem resides
      newPath - - path containing the file/directory that represents this file descriptor
    • valid

      public boolean valid()
      Tests if this file descriptor object is valid.
      Returns:
      true if the file descriptor object represents a valid, open file, socket, or other active I/O connection; false otherwise.
    • sync

      public void sync() throws OWSyncFailedException
      Force all system buffers to synchronize with the underlying device. This method returns after all modified data and attributes of this FileDescriptor have been written to the relevant device(s). In particular, if this FileDescriptor refers to a physical storage medium, such as a file in a file system, sync will not return until all in-memory modified copies of buffers associated with this FileDesecriptor have been written to the physical medium. sync is meant to be used by code that requires physical storage (such as a file) to be in a known state For example, a class that provided a simple transaction facility might use sync to ensure that all changes to a file caused by a given transaction were recorded on a storage medium. sync only affects buffers downstream of this FileDescriptor. If any in-memory buffering is being done by the application (for example, by a BufferedOutputStream object), those buffers must be flushed into the OWFileDescriptor (for example, by invoking OutputStream.flush) before that data will be affected by sync.

      This method may be called multiple times if the source of OWSyncFailedException has been rectified (1-Wire device was reattached to the network).

      Throws:
      OWSyncFailedException - Thrown when the buffers cannot be flushed, or because the system cannot guarantee that all the buffers have been synchronized with physical media.
    • open

      protected void open() throws OWFileNotFoundException
      Opens the file for reading. If successful (no exceptions) then the following class member variables will be set:
      • fePage - File Entry page number
      • feOffset - Offset into File Entry page
      • feData - buffer containing the last File Entry Page
      • feLen - length of packet in the last File Entry Page
      • feNumPages - Number of Pages specified in File Entry
      • feStartPage - Start Page specified in the File Entry
      • feParentPage - Parent page of current File Entry Page
      • feParentOffset - Offset into Parent page
      • lastPage - (file only) last page read
      • lastOffset - (file only) offset into last page read
      • lastLen - (file only) length of last page read
      • lastPageData - (file only) buffer for the last page read
      • filePosition - (file only) overall file position when reading
      Throws:
      OWFileNotFoundException - when the file/directory path is invalid or there was an IOException thrown when trying to read the device.
    • close

      protected void close() throws IOException
      Closes this file descriptor and releases any system resources associated with this stream. Any cached writes are flushed into the filesystem. This file descriptor may no longer be used for writing bytes. If successful (no exceptions) then the following class member variables will be set:
      • fePage - File Entry page number
      • feOffset - Offset into File Entry page
      • feData - buffer containing the last File Entry Page
      • feLen - length of packet in the last File Entry Page
      • feNumPages - Number of Pages specified in File Entry
      • feStartPage - Start Page specified in the File Entry
      • feParentPage - Parent page of current File Entry Page
      • feParentOffset - Offset into Parent page
      • lastPage - (file only) last page read
      • lastOffset - (file only) offset into last page read
      • lastLen - (file only) length of last page read
      • lastPageData - (file only) buffer for the last page read
      • filePosition - (file only) overall file position when reading
      Throws:
      IOException - if an I/O error occurs
    • create

      protected void create(boolean append, boolean isDirectory, boolean makeParents, int startPage, int numberPages) throws OWFileNotFoundException
      Creates a directory or file to write.
      Parameters:
      append - for files only, true to append data to end of file, false to reset the file
      isDirectory - true if creating a directory, false for a file
      makeParents - true if creating all needed parent directories in order to create the file/directory
      startPage - starting page of file/directory, -1 if not renaming
      numberPages - number of pages in file/directory, -1 if not renaming
      Throws:
      OWFileNotFoundException - if file already opened to write, if makeParents=false and parent directories not found, if file is read only, or if there is an IO error reading filesystem
    • format

      protected void format() throws OneWireException, OneWireIOException
      Format the Filesystem on the 1-Wire device.

      WARNING: all files/directories will be deleted in the process.

      Throws:
      OneWireException - when adapter is not setup properly
      OneWireIOException - when an IO error occurred reading the 1-Wire device
    • read

      protected 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.
      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.
    • read

      protected int read() throws IOException
      Reads a byte of data from this input stream. This method blocks if no input is yet available.
      Returns:
      the next byte of data, or -1 if the end of the file is reached.
      Throws:
      IOException - if an I/O error occurs.
    • skip

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

      protected int available() throws IOException
      Returns the number of bytes that can be read from this file input stream without blocking.
      Returns:
      the number of bytes that can be read from this file input stream without blocking.
      Throws:
      IOException - if an I/O error occurs.
    • write

      protected void write(int b) throws IOException
      Writes the specified byte to this file output stream. Implements the write method of OutputStream.
      Parameters:
      b - the byte to be written.
      Throws:
      IOException - if an I/O error occurs.
    • write

      protected void write(byte[] b, int off, int len) throws IOException
      Writes len bytes from the specified byte array starting at offset off to this file output stream.
      Parameters:
      b - the data.
      off - the start offset in the data.
      len - the number of bytes to write.
      Throws:
      IOException - if an I/O error occurs.
    • getName

      protected String getName()
      Returns the name of the file or directory denoted by this abstract pathname. This is just the last name in the pathname's name sequence. If the pathname's name sequence is empty, then the empty string is returned.
      Returns:
      The name of the file or directory denoted by this abstract pathname, or the empty string if this pathname's name sequence is empty
    • getParent

      protected String getParent()
      Returns the pathname string of this abstract pathname's parent, or null if this pathname does not name a parent directory.

      The parent of an abstract pathname consists of the pathname's prefix, if any, and each name in the pathname's name sequence except for the last. If the name sequence is empty then the pathname does not name a parent directory.

      Returns:
      The pathname string of the parent directory named by this abstract pathname, or null if this pathname does not name a parent
    • getPath

      protected String getPath()
      Converts this abstract pathname into a pathname string. The resulting string uses the default name-separator character to separate the names in the name sequence.
      Returns:
      The string form of this abstract pathname
    • exists

      protected boolean exists()
      Checks to see if the file exists
      Returns:
      true if the file exists and false otherwise
    • canRead

      protected boolean canRead()
      Checks to see if can read the file associated with this descriptor.
      Returns:
      true if this file exists, false otherwise
    • canWrite

      protected boolean canWrite()
      Checks to see if the file represented by this descriptor is writable.
      Returns:
      true if this file exists and is not read only, false otherwise
    • isDirectory

      protected boolean isDirectory()
      Checks to see if this is a directory.
      Returns:
      true if this file exists and it is a directory, false otherwise
    • isFile

      protected boolean isFile()
      Checks to see if this is a file
      Returns:
      true if this file exists and is a file, false otherwise
    • isHidden

      protected boolean isHidden()
      Checks to see if this directory is hidden.
      Returns:
      true if this is a directory and is marked as hidden, false otherwise
    • length

      protected long length()
      Get the estimated length of the file represented by this descriptor. This is calculated by looking at how may pages the file is using so is not a very accurate measure.
      Returns:
      estimated length of file in bytes
    • delete

      protected boolean delete()
      Delete this file or directory represented by this descriptor. Will fail if it is a read-only file or a non-empty directory.
      Returns:
      true if the file/directory was successfully deleted or false if not
    • list

      protected String[] list()
      Returns an array of strings naming the files and directories in the directory denoted by this abstract pathname.

      If this abstract pathname does not denote a directory, then this method returns null. Otherwise an array of strings is returned, one for each file or directory in the directory. Names denoting the directory itself and the directory's parent directory are not included in the result. Each string is a file name rather than a complete path.

      There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not, in particular, guaranteed to appear in alphabetical order.

      Returns:
      An array of strings naming the files and directories in the directory denoted by this abstract pathname. The array will be empty if the directory is empty. Returns null if this abstract pathname does not denote a directory, or if an I/O error occurs.
    • renameTo

      protected boolean renameTo(OWFile dest)
      Renames the file denoted by this abstract pathname.
      Parameters:
      dest - The new abstract pathname for the named file
      Returns:
      true if and only if the renaming succeeded; false otherwise
      Throws:
      NullPointerException - If parameter dest is null
    • setReadOnly

      protected boolean setReadOnly()
      Marks the file or directory named by this abstract pathname so that only read operations are allowed. After invoking this method the file or directory is guaranteed not to change until it is either deleted or marked to allow write access. Whether or not a read-only file or directory may be deleted depends upon the underlying system.
      Returns:
      true if and only if the operation succeeded; false otherwise
    • mark

      protected void mark(int readlimit)
      Mark the current position in the file being read for later reference.
      Parameters:
      readlimit - limit to keep track of the current position
    • reset

      protected void reset() throws IOException
      Reset the the read of this file back to the marked position.
      Throws:
      IOException - when a read error occurs
    • markPageUsed

      protected void markPageUsed(int page) throws OneWireException
      Mark the specified page as used in the page bitmap.
      Parameters:
      page - number to mark as used
      Throws:
      OneWireException - when an IO exception occurs
    • freePage

      protected boolean freePage(int page) throws OneWireException
      free the specified page as being un-used in the page bitmap
      Parameters:
      page - number to mark as un-used
      Returns:
      true if the page as be been marked as un-used, false if the page is on an OTP device and cannot be freed
      Throws:
      OneWireException - when an IO error occurs
    • getFirstFreePage

      protected int getFirstFreePage(boolean counterPage) throws OneWireException
      Get the first free page from the page bitmap.
      Parameters:
      counterPage - true if page needed is a 'counter' page (used in for monetary files)
      Returns:
      first page number that is free to write
      Throws:
      OneWireException - when an IO exception occurs
    • getNextFreePage

      protected int getNextFreePage(boolean counterPage) throws OneWireException
      Get the next free page from the page bitmap.
      Parameters:
      counterPage - true if page needed is a 'counter' page (used in for monetary files)
      Returns:
      next page number that is free to write
      Throws:
      OneWireException - when an IO exception occurs
    • getFreeMemory

      protected int getFreeMemory() throws OneWireException
      Gets the number of bytes available on this device for file and directory information.
      Returns:
      number of free bytes
      Throws:
      OneWireException - when an IO exception occurs
    • writeBitMap

      protected void writeBitMap() throws OneWireException
      Write the page bitmap back to the device.
      Throws:
      OneWireException - when an IO error occurs
    • readBitMap

      protected void readBitMap() throws OneWireException
      Read the page bitmap.
      Throws:
      OneWireException - when an IO error occurs
    • getPageList

      protected int[] getPageList() throws OneWireException
      Gets an array of integers that represents the page list of the file or directory represented by this OWFile.
      Throws:
      OneWireException - if an I/O error occurs.
    • getStartPage

      protected int getStartPage() throws IOException
      Returns an integer which represents the starting memory page of the file or directory represented by this OWFile.
      Returns:
      The starting page of the file or directory.
      Throws:
      IOException - if the file doesn't exist
    • getMemoryBankForPage

      protected PagedMemoryBank getMemoryBankForPage(int page)
      Gets the memory bank object for the specified page. This is significant if the Filesystem spans memory banks on the same or different devices.
    • getLocalPage

      protected int getLocalPage(int page)
      Gets the local page number on the memory bank object for the specified page. This is significant if the Filesystem spans memory banks on the same or different devices.
    • verifyDeviceMap

      protected int verifyDeviceMap(int startPage, int numberOfContainers, boolean setOverdrive) throws OneWireException
      Verify the Device Map of a MASTER device is correct.
      Parameters:
      startPage - starting page number of the device map file
      numberOfContainers - to re-create the OneWireContainer array in the instance variable from the devices listed in the device map 'owd[]'. Zero indicates leave the list alone. >0 means recreate the array keeping the same MASTER device.
      setOverdrive - true if set new containers to do a max speed of overdrive if possible
      Returns:
      the number of devices in the device map if the current device list is INVALID and returns zero if the current device list is VALID.
      Throws:
      OneWireException - when an IO error occurs
    • createNewFile

      protected boolean createNewFile() throws IOException
      Atomically creates a new, empty file named by this abstract pathname if and only if a file with this name does not yet exist. The check for the existence of the file and the creation of the file if it does not exist are a single operation that is atomic with respect to all other filesystem activities that might affect the file.
      Returns:
      true if the named file does not exist and was successfully created; false if the named file already exists
      Throws:
      IOException - If an I/O error occurred
    • getHashCode

      protected int getHashCode()
      Computes a hash code for this abstract pathname. Because equality of abstract pathnames is inherently system-dependent, so is the computation of their hash codes. On UNIX systems, the hash code of an abstract pathname is equal to the exclusive or of its pathname string and the decimal value 1234321. On Win32 systems, the hash code is equal to the exclusive or of its pathname string, converted to lower case, and the decimal value 1234321.
      Returns:
      A hash code for this abstract pathname
    • getOneWireContainers

      protected OneWireContainer[] getOneWireContainers()
      Gets the OneWireContainers that represent this Filesystem.
      Returns:
      array of OneWireContainer's that represent this Filesystem.
    • free

      protected void free()
      Free's this file descriptors system resources.