Class OWFileDescriptor


  • public class OWFileDescriptor
    extends java.lang.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:
    OWFile, OWFileInputStream, OWFileOutputStream
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
        OWFileDescriptor()
      Construct an invalid 1-Wire FileDescriptor
      protected OWFileDescriptor​(OneWireContainer[] owd, java.lang.String newPath)
      Construct a 1-Wire FileDescrioptor providing the Filesystem 1-Wire device and file path.
      protected OWFileDescriptor​(OneWireContainer owd, java.lang.String newPath)
      Construct a 1-Wire FileDescrioptor providing the Filesystem 1-Wire device and file path.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected int available()
      Returns the number of bytes that can be read from this file input stream without blocking.
      protected boolean canRead()
      Checks to see if can read the file associated with this descriptor.
      protected boolean canWrite()
      Checks to see if the file represented by this descriptor is writable.
      protected void close()
      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 createNewFile()
      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()
      Delete this file or directory represented by this descriptor.
      protected boolean exists()
      Checks to see if the file exists
      protected void format()
      Format the Filesystem on the 1-Wire device.
      protected void free()
      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 getFreeMemory()
      Gets the number of bytes available on this device for file and directory information.
      protected int getHashCode()
      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 getMemoryBankForPage​(int page)
      Gets the memory bank object for the specified page.
      protected java.lang.String getName()
      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[] getOneWireContainers()
      Gets the OneWireContainers that represent this Filesystem.
      protected int[] getPageList()
      Gets an array of integers that represents the page list of the file or directory represented by this OWFile.
      protected java.lang.String getParent()
      Returns the pathname string of this abstract pathname's parent, or null if this pathname does not name a parent directory.
      protected java.lang.String getPath()
      Converts this abstract pathname into a pathname string.
      protected int getStartPage()
      Returns an integer which represents the starting memory page of the file or directory represented by this OWFile.
      protected boolean isDirectory()
      Checks to see if this is a directory.
      protected boolean isFile()
      Checks to see if this is a file
      protected boolean isHidden()
      Checks to see if this directory is hidden.
      protected long length()
      Get the estimated length of the file represented by this descriptor.
      protected java.lang.String[] list()
      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 open()
      Opens the file for reading.
      protected int read()
      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 readBitMap()
      Read the page bitmap.
      protected boolean renameTo​(OWFile dest)
      Renames the file denoted by this abstract pathname.
      protected void reset()
      Reset the the read of this file back to the marked position.
      protected boolean setReadOnly()
      Marks the file or directory named by this abstract pathname so that only read operations are allowed.
      protected void setupFD​(OneWireContainer[] owd, java.lang.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 sync()
      Force all system buffers to synchronize with the underlying device.
      boolean valid()
      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 writeBitMap()
      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 Detail

      • OWFileDescriptor

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

        protected OWFileDescriptor​(OneWireContainer owd,
                                   java.lang.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,
                                   java.lang.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 Detail

      • setupFD

        protected void setupFD​(OneWireContainer[] owd,
                               java.lang.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 java.io.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:
        java.io.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
      • read

        protected int read​(byte[] b,
                           int off,
                           int len)
                    throws java.io.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:
        java.io.IOException - if an I/O error occurs.
      • read

        protected int read()
                    throws java.io.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:
        java.io.IOException - if an I/O error occurs.
      • skip

        protected long skip​(long n)
                     throws java.io.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:
        java.io.IOException - if an I/O error occurs.
      • available

        protected int available()
                         throws java.io.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:
        java.io.IOException - if an I/O error occurs.
      • write

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

        protected void write​(byte[] b,
                             int off,
                             int len)
                      throws java.io.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:
        java.io.IOException - if an I/O error occurs.
      • getName

        protected java.lang.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 java.lang.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 java.lang.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 java.lang.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:
        java.lang.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 java.io.IOException
        Reset the the read of this file back to the marked position.
        Throws:
        java.io.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
      • 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 java.io.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:
        java.io.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 java.io.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:
        java.io.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.