com.dalsemi.onewire.utils
Class OWFileOutputStream

java.lang.Object
  |
  +--java.io.OutputStream
        |
        +--com.dalsemi.onewire.utils.OWFileOutputStream

public class OWFileOutputStream

extends 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 accomodate 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();
  

Version:

0.01, 1 June 2001

See Also:

OWFile, OWFileDescriptor, OWFileInputStream

Constructor Summary

OWFileOutputStream(OneWireContainer[] owd, String name)
Creates an output file stream to write to the file with the specified name.

OWFileOutputStream(OneWireContainer[] owd, String name, boolean append)
Creates an output file stream to write to the file with the specified name.

OWFileOutputStream(OneWireContainer owd, String name)
Creates an output file stream to write to the file with the specified name.

OWFileOutputStream(OneWireContainer owd, String name, boolean append)
Creates an output file stream to write to the file with the specified name.

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.

Method Summary

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

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OWFileOutputStream

public OWFileOutputStream(OneWireContainer owd,
                          String name)
                   throws FileNotFoundException

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:

FileNotFoundException - 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

SecurityException - if a security manager exists and its checkWrite method denies write access to the file.

OWFileOutputStream

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

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:

FileNotFoundException - 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

SecurityException - if a security manager exists and its checkWrite method denies write access to the file.

OWFileOutputStream

public OWFileOutputStream(OneWireContainer owd,
                          String name,
                          boolean append)
                   throws FileNotFoundException

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:

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

SecurityException - if a security manager exists and its checkWrite method denies write access to the file.

OWFileOutputStream

public OWFileOutputStream(OneWireContainer[] owd,
                          String name,
                          boolean append)
                   throws FileNotFoundException

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:

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

SecurityException - if a security manager exists and its checkWrite method denies write access to the file.

OWFileOutputStream

public OWFileOutputStream(OWFile file)
                   throws FileNotFoundException

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:

FileNotFoundException - 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

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:

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 IOException

Writes the specified byte to this file output stream. Implements the write method of OutputStream.

Overrides:

write in class OutputStream

Parameters:

b - the byte to be written.

Throws:

IOException - if an I/O error occurs.

write

public void write(byte[] b)
           throws IOException

Writes b.length bytes from the specified byte array to this file output stream.

Overrides:

write in class OutputStream

Parameters:

b - the data.

Throws:

IOException - if an I/O error occurs.

write

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

Overrides:

write in class OutputStream

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.

close

public void close()
           throws 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.

Overrides:

close in class OutputStream

Throws:

IOException - if an I/O error occurs.

getFD

public OWFileDescriptor getFD()
                       throws 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:

IOException - if an I/O error occurs.

See Also:

OWFileDescriptor

finalize

public void finalize()
              throws 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.

Throws:

IOException - if an I/O error occurs.

See Also:

OWFileInputStream.close()