Class OWFileOutputStream

  • All Implemented Interfaces:
    java.io.Closeable, java.io.Flushable, java.lang.AutoCloseable

    public class OWFileOutputStream
    extends java.io.OutputStream
    A 1-Wire file output stream is an output stream for writing data to a OWFile or to a OWFileDescriptor. Whether or not a file is available or may be created depends upon the underlying platform. This platform allows a file to be opened for writing by only one OWFileOutputStream (or other file-writing object) at a time. In such situations the constructors in this class will fail if the file involved is already open. The 1-Wire File system must be formatted before use. Use OWFile:format to prepare a device or group of devices.

    The 1-Wire device will only be written in the following situations

    • use getFD() and call the sync() method of the OWFileDescriptor until a SyncFailedException is NOT thrown
    • if the device runs out of memory during a write, before IOException is thrown
    • by calling close()
    • in finalize() WARNING could deadlock if device not synced and inside beginExclusive/endExclusive block.

    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 accommodate legacy implementations

    Usage

    Example

    Write to a 1-Wire file on device 'owd':
      
       // create a 1-Wire file at root
       OWFileOutputStream outstream = new OWFileOutputStream(owd, "DEMO.0");
    
       // write the data (in a byte array data[])
       outstream.write(data);
    
       // get 1-Wire File descriptor to flush to device
       OWFileDescriptor owfd = owfile.getFD();
    
       // loop until sync is successful
       do
       {
          try
          {
             owfd.sync();
             done = true;
          }
          catch (SyncFailedException e)
          {
             // do something
             ...
             done = false;
          }
       }
       while (!done)
    
       // close the stream to release system resources
       outstream.close();
     
     
    See Also:
    OWFile, OWFileDescriptor, OWFileInputStream
    • Constructor Summary

      Constructors 
      Constructor Description
      OWFileOutputStream​(OWFile file)
      Creates a file output stream to write to the file represented by the specified File object.
      OWFileOutputStream​(OWFileDescriptor fdObj)
      Creates an output file stream to write to the specified file descriptor, which represents an existing connection to an actual file in the Filesystem.
      OWFileOutputStream​(OneWireContainer[] owd, java.lang.String name)
      Creates an output file stream to write to the file with the specified name.
      OWFileOutputStream​(OneWireContainer[] owd, java.lang.String name, boolean append)
      Creates an output file stream to write to the file with the specified name.
      OWFileOutputStream​(OneWireContainer owd, java.lang.String name)
      Creates an output file stream to write to the file with the specified name.
      OWFileOutputStream​(OneWireContainer owd, java.lang.String name, boolean append)
      Creates an output file stream to write to the file with the specified name.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Closes this file output stream and releases any system resources associated with this stream.
      void finalize()
      Cleans up the connection to the file, and ensures that the close method of this file output stream is called when there are no more references to this stream.
      OWFileDescriptor getFD()
      Returns the file descriptor associated with this stream.
      void write​(byte[] b)
      Writes b.length bytes from the specified byte array to this file output stream.
      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.
      void write​(int b)
      Writes the specified byte to this file output stream.
      • Methods inherited from class java.io.OutputStream

        flush, nullOutputStream
      • Methods inherited from class java.lang.Object

        clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • OWFileOutputStream

        public OWFileOutputStream​(OneWireContainer owd,
                                  java.lang.String name)
                           throws OWFileNotFoundException
        Creates an output file stream to write to the file with the specified name. A new OWFileDescriptor object is created to represent this file connection.

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

        If the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason then a FileNotFoundException is thrown.

        Parameters:
        owd - OneWireContainer that this Filesystem resides on
        name - the system-dependent filename
        Throws:
        OWFileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason
        java.lang.SecurityException - if a security manager exists and its checkWrite method denies write access to the file.
      • OWFileOutputStream

        public OWFileOutputStream​(OneWireContainer[] owd,
                                  java.lang.String name)
                           throws OWFileNotFoundException
        Creates an output file stream to write to the file with the specified name. A new OWFileDescriptor object is created to represent this file connection.

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

        If the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason then a FileNotFoundException is thrown.

        Parameters:
        owd - array of OneWireContainers that this Filesystem resides on
        name - the system-dependent filename
        Throws:
        OWFileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason
      • OWFileOutputStream

        public OWFileOutputStream​(OneWireContainer owd,
                                  java.lang.String name,
                                  boolean append)
                           throws OWFileNotFoundException
        Creates an output file stream to write to the file with the specified name. If the second argument is true, then bytes will be written to the end of the file rather than the beginning. A new OWFileDescriptor object is created to represent this file connection.

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

        If the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason then a FileNotFoundException is thrown.

        Parameters:
        owd - OneWireContainer that this Filesystem resides on
        name - the system-dependent file name
        append - if true, then bytes will be written to the end of the file rather than the beginning
        Throws:
        OWFileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason.
        java.lang.SecurityException - if a security manager exists and its checkWrite method denies write access to the file.
      • OWFileOutputStream

        public OWFileOutputStream​(OneWireContainer[] owd,
                                  java.lang.String name,
                                  boolean append)
                           throws OWFileNotFoundException
        Creates an output file stream to write to the file with the specified name. If the second argument is true, then bytes will be written to the end of the file rather than the beginning. A new OWFileDescriptor object is created to represent this file connection.

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

        If the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason then a FileNotFoundException is thrown.

        Parameters:
        owd - array of OneWireContainers that this Filesystem resides on
        name - the system-dependent file name
        append - if true, then bytes will be written to the end of the file rather than the beginning
        Throws:
        OWFileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason.
        java.lang.SecurityException - if a security manager exists and its checkWrite method denies write access to the file.
      • OWFileOutputStream

        public OWFileOutputStream​(OWFile file)
                           throws OWFileNotFoundException
        Creates a file output stream to write to the file represented by the specified File object. A new OWFileDescriptor object is created to represent this file connection.

        First, if there is a security manager, its checkWrite method is called with the path represented by the file argument as its argument.

        If the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason then a FileNotFoundException is thrown.

        Parameters:
        file - the file to be opened for writing.
        Throws:
        OWFileNotFoundException - if the file exists but is a directory rather than a regular file, does not exist but cannot be created, or cannot be opened for any other reason
        java.lang.SecurityException - if a security manager exists and its checkWrite method denies write access to the file.
        See Also:
        File.getPath()
      • OWFileOutputStream

        public OWFileOutputStream​(OWFileDescriptor fdObj)
        Creates an output file stream to write to the specified file descriptor, which represents an existing connection to an actual file in the Filesystem.

        First, if there is a security manager, its checkWrite method is called with the file descriptor fdObj argument as its argument.

        Parameters:
        fdObj - the file descriptor to be opened for writing.
        Throws:
        java.lang.SecurityException - if a security manager exists and its checkWrite method denies write access to the file descriptor.
    • Method Detail

      • write

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

        public void write​(byte[] b)
                   throws java.io.IOException
        Writes b.length bytes from the specified byte array to this file output stream.
        Overrides:
        write in class java.io.OutputStream
        Parameters:
        b - the data.
        Throws:
        java.io.IOException - if an I/O error occurs.
      • write

        public 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.
        Overrides:
        write in class java.io.OutputStream
        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.
      • close

        public void close()
                   throws java.io.IOException
        Closes this file output stream and releases any system resources associated with this stream. This file output stream may no longer be used for writing bytes.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Overrides:
        close in class java.io.OutputStream
        Throws:
        java.io.IOException - if an I/O error occurs.
      • getFD

        public OWFileDescriptor getFD()
                               throws java.io.IOException
        Returns the file descriptor associated with this stream.
        Returns:
        the OWFileDescriptor object that represents the connection to the file in the Filesystem being used by this FileOutputStream object.
        Throws:
        java.io.IOException - if an I/O error occurs.
        See Also:
        OWFileDescriptor
      • finalize

        public void finalize()
                      throws java.io.IOException
        Cleans up the connection to the file, and ensures that the close method of this file output stream is called when there are no more references to this stream.
        Overrides:
        finalize in class java.lang.Object
        Throws:
        java.io.IOException - if an I/O error occurs.
        See Also:
        OWFileInputStream.close()