owfile.java

这是一个以JAVA编写的程序,本人还没有试过,是一个简单的温度控制系统

/*---------------------------------------------------------------------------
 * Copyright (C) 2001 Dallas Semiconductor Corporation, All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL DALLAS SEMICONDUCTOR BE LIABLE FOR ANY CLAIM, DAMAGES
 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 *
 * Except as contained in this notice, the name of Dallas Semiconductor
 * shall not be used except as stated in the Dallas Semiconductor
 * Branding Policy.
 *---------------------------------------------------------------------------
 */

package com.dalsemi.onewire.application.file;

import java.io.IOException;
import java.io.FileNotFoundException;
import com.dalsemi.onewire.container.OneWireContainer;
import com.dalsemi.onewire.OneWireException;
import com.dalsemi.onewire.container.PagedMemoryBank;
import com.dalsemi.onewire.utils.Convert;

/**
 * An abstract representation of file and directory pathnames on 1-Wire devices.
 *
 * <p> User interfaces and operating systems use system-dependent <em>pathname
 * strings</em> to name files and directories.  This class presents an
 * abstract, system-independent view of hierarchical pathnames.  An
 * <em>abstract pathname</em> has two components:
 *
 * <ol>
 * <li> An optional system-dependent <em>prefix</em> string,<br>
 *      such as a disk-drive specifier, <code>"/"</code> for the UNIX root
 *      directory, or <code>"\\"</code> for a Win32 UNC pathname, and
 * <li> A sequence of zero or more string <em>names</em>.
 * </ol>
 *
 * Each name in an abstract pathname except for the last denotes a directory;
 * the last name may denote either a directory or a file.  The <em>empty</em>
 * abstract pathname has no prefix and an empty name sequence.
 *
 * <p> The conversion of a pathname string to or from an abstract pathname is
 * inherently system-dependent.  When an abstract pathname is converted into a
 * pathname string, each name is separated from the next by a single copy of
 * the default <em>separator character</em>.  The default name-separator
 * character is defined by the system property <code>OWFile.separator</code>, and
 * is made available in the public static fields <code>{@link
 * #separator}</code> and <code>{@link #separatorChar}</code> of this class.
 * When a pathname string is converted into an abstract pathname, the names
 * within it may be separated by the default name-separator character or by any
 * other name-separator character that is supported by the underlying system.
 *
 * <p> A pathname, whether abstract or in string form, may be either
 * <em>absolute</em> or <em>relative</em>.  An absolute pathname is complete in
 * that no other information is required in order to locate the file that it
 * denotes.  A relative pathname, in contrast, must be interpreted in terms of
 * information taken from some other pathname.  By default the classes in the
 * <code>java.io</code> package always resolve relative pathnames against the
 * current user directory.  This directory is named by the system property
 * <code>user.dir</code>, and is typically the directory in which the Java
 * virtual machine was invoked.  The pathname provided to this OWFile
 * however is always <em>absolute</em>.
 *
 * <p> The prefix concept is used to handle root directories on UNIX platforms,
 * and drive specifiers, root directories and UNC pathnames on Win32 platforms,
 * as follows:
 *
 * <ul>
 * <li> For 1-Wire the Filesystem , the prefix of an absolute pathname is always
 * <code>"/"</code>.  The abstract pathname denoting the root directory
 * has the prefix <code>"/"</code> and an empty name sequence.
 *
 * </ul>
 *
 * <p> Instances of the <code>OWFile</code> class are immutable; that is, once
 * created, the abstract pathname represented by a <code>OWFile</code> object
 * will never change.
 *
 * <H3> What is Different on the 1-Wire Filesystem </H3>
 * <p> The methods in the class are the same as in the java.io.File version 1.2
 *     with the following exceptions
 * <p>
 * <p> Methods provided but of <b> limited </b> functionallity
 * <ul>
 * <li>   public long lastModified() - always returns 0
 * <li>   public boolean isAbsolute() - always true
 * <li>   public boolean setLastModified(long time) - does nothing
 * <li>   public boolean setReadOnly() - only for files
 * <li>   public boolean isHidden() - only could be true for directories
 * </ul>
 *
 * <p> Methods <b> not </b> provided or supported:
 * <ul>
 * <li>   public void deleteOnExit()
 * <li>   public String[] list(FilenameFilter filter)
 * <li>   public File[] listFiles(FilenameFilter filter)
 * <li>   public File[] listFiles(FileFilter filter)
 * <li>   public static File createTempFile(String prefix, String suffix, File directory)
 * <li>   public static File createTempFile(String prefix, String suffix)
 * <li>   public URL toURL()
 * </ul>
 *
 * <p> <b> Extra </b> Methods (not usually in 1.2 java.io.File)
 * <ul>
 * <li>   public OWFileDescriptor getFD()
 * <li>   public void close()
 * <li>   public OneWireContainer getOneWireContainer()
 * <li>   public void format()
 * <li>   public int getFreeMemory()
 * <li>   public int[] getPageList()
 * <li>   public PagedMemoryBank getMemoryBankForPage(int)
 * <li>   public int getLocalPage(int)
 * </ul>
 *
 * <p>  File and directory <b> name </b> limitations
 * <ul>
 * <li> File/directory names limited to 4 characters not including extension
 * <li> File/directory names are not case sensitive and will be automatically
 *      changed to all-CAPS
 * <li> Only files can have extensions
 * <li> Extensions are numberical in the range 0 to 125
 * <li> Extensions 100 to 125 are special purpose and not yet implemented or allowed
 * <li> Files can have the read-only attribute
 * <li> Directories can have the hidden attribute
 * <li> It is recommended to limit directory depth to 10 levels to accomodate
 *      legacy implementations
 * </ul>
 *
 * <H3> Tips </H3>
 * <ul>
 * <li> <i> Writes </i> will not be flushed to the 1-Wire device Filesystem
 *      until the <code> OWFile </code> instance is closed with the
 *      <code> close() </code> method or the <code> sync() </code> method
 *      from the OWFileDescriptor
 * <li> The <code> sync() </code> method for flushing the changes to the
 *      Filesystem is preferred since it can be called multiple times if
 *      there is a connection problem
 * <li> New 1-Wire devices Filesystem must first be formatted with the
 *      <code> format() </code> method in order for files or directories to
 *      be added or changed.
 * <li> Multiple 1-Wire devices can be linked into a common Filesystem by
 *      using the constructor that accepts an array of 1-Wire devices.  The
 *      first device in the list is the 'root' device and the rest will be
 *      designated 'satelite's.  Once the <code> format() </code> method
 *      is used to link these devices then only the 'root' need be used
 *      in future constuctors of this class or the 1-Wire file stream classes.
 * <li> Only rewrittable 1-Wire memory devices can be used in multi-device
 *      file systems.  EPROM and write-once devices can only be used in
 *      single device file systems.
 * <li> 1-Wire devices have a limited amount of space.  Use the
 *      <code> getFreeMemory() </code> method to get an estimate of free memory
 *      available.
 * <li> Call the <code> close() </code> method to release system resources
 *      allocated when done with the <code> OWFile </code> instance
 * </ul>
 *
 * <H3> Usage </H3>
 * <DL>
 * <DD> <H4> Example 1</H4>
 * Format the Filesystem of the 1-Wire device 'owd':
 * <PRE> <CODE>
 *   // create a 1-Wire file at root
 *   OWFile owfile = new OWFile(owd, "");
 *
 *   // format Filesystem
 *   owfile.format();
 *
 *   // 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 1-Wire file to release system resources
 *   owfile.close();
 * </CODE> </PRE>
 *
 * <DD> <H4> Example 2</H4>
 * Make a multi-level directory structure on the 1-Wire device 'owd':
 * <PRE> <CODE>
 *   OWFile owfile = new OWFile(owd, "/doc/text/temp");
 *
 *   // make the directories
 *   if (owfile.mkdirs())
 *      System.out.println("Success!");
 *   else
 *      System.out.println("Out of memory or invalid file/directory");
 *
 *   // get 1-Wire File descriptor to flush to device
 *   ...
 * </CODE> </PRE>
 * </DL>
 *
 * <H3> 1-Wire File Structure Format </H3>
 * <DL>
 * <DD><A HREF="http://pdfserv.maxim-ic.com/arpdf/AppNotes/app114.pdf"> http://pdfserv.maxim-ic.com/arpdf/AppNotes/app114.pdf</A>
 * </DL>
 *
 * @see com.dalsemi.onewire.application.file.OWFileDescriptor
 * @see com.dalsemi.onewire.application.file.OWFileInputStream
 * @see com.dalsemi.onewire.application.file.OWFileOutputStream
 *
 * @author  DS
 * @version 0.01, 1 June 2001
 */
public class OWFile
{

   //--------
   //-------- Static Variables
   //--------

   /** Field separator */
   public static final String separator = "/";

   /** Field separatorChar */
   public static final char separatorChar = '/';

   /** Field pathSeparator */
   public static final String pathSeparator = ":";

   /** Field pathSeparatorChar */
   public static final char pathSeparatorChar = ':';

   //--------
   //-------- Variables
   //--------

   /** Abstract file descriptor containing this file */
   private OWFileDescriptor fd;

   //--------
   //-------- Constructor
   //--------

   /**
    * Creates a new <code>OWFile</code> instance by converting the given
    * pathname string into an abstract pathname.  If the given string is
    * the empty string, then the result is the empty abstract pathname.
    *
    * @param   owd    OneWireContainer that this Filesystem resides on
    * @param   pathname  A pathname string
    * @throws  NullPointerException
    *          If the <code>pathname</code> argument is <code>null</code>
    */
   public OWFile(OneWireContainer owd, String pathname)
   {
      fd          = new OWFileDescriptor(owd, pathname);
   }

   /**
    * Creates a new <code>OWFile</code> instance by converting the given
    * pathname string into an abstract pathname.  If the given string is
    * the empty string, then the result is the empty abstract pathname.
    *
    * @param   owd  ordered array of OneWireContainers that this Filesystem
    *               resides on
    * @param   pathname  A pathname string
    * @throws  NullPointerException
    *          If the <code>pathname</code> argument is <code>null</code>

        Change the OWFileDescriptor to accept only an array of containers
        Change the local ref to be an array
        Create a single array in constructors with single passed owc

    */
   public OWFile(OneWireContainer[] owd, String pathname)
   {
      fd       = new OWFileDescriptor(owd, pathname);
   }

   /* Note: The two-argument File constructors do not interpret an empty
      parent abstract pathname as the current user directory.  An empty parent
      instead causes the child to be resolved against the system-dependent
      directory defined by the FileSystem.getDefaultParent method.  On Unix
      this default is "/", while on Win32 it is "\\".  This is required for
      compatibility with the original behavior of this class. */

   /**
    * Creates a new <code>OWFile</code> instance from a parent pathname string
    * and a child pathname string.
    *
    * <p> If <code>parent</code> is <code>null</code> then the new
    * <code>OWFile</code> instance is created as if by invoking the
    * single-argument <code>OWFile</code> constructor on the given
    * <code>child</code> pathname string.
    *
    * <p> Otherwise the <code>parent</code> pathname string is taken to denote
    * a directory, and the <code>child</code> pathname string is taken to
    * denote either a directory or a file.  If the <code>child</code> pathname
    * string is absolute then it is converted into a relative pathname in a
    * system-dependent way.  If <code>parent</code> is the empty string then
    * the new <code>OWFile</code> instance is created by converting
    * <code>child</code> into an abstract pathname and resolving the result
    * against a system-dependent default directory.  Otherwise each pathname
    * string is converted into an abstract pathname and the child abstract
    * pathname is resolved against the parent.
    *
    * @param   owd    OneWireContainer that this Filesystem resides on
    * @param   parent  The parent pathname string
    * @param   child   The child pathname string
    * @throws  NullPointerException
    *          If <code>child</code> is <code>null</code>
    */
   public OWFile(OneWireContainer owd, String parent, String child)
   {
      if (child == null)
         throw new NullPointerException("child is null");

      fd = new OWFileDescriptor(owd, parent + child);
   }

   /**
    * Creates a new <code>OWFile</code> instance from a parent abstract
    * pathname and a child pathname string.
    *
    * <p> If <code>parent</code> is <code>null</code> then the new
    * <code>OWFile</code> instance is created as if by invoking the
    * single-argument <code>OWFile</code> constructor on the given
    * <code>child</code> pathname string.
    *
    * <p> Otherwise the <code>parent</code> abstract pathname is taken to
    * denote a directory, and the <code>child</code> pathname string is taken
    * to denote either a directory or a file.  If the <code>child</code>
    * pathname string is absolute then it is converted into a relative
    * pathname in a system-dependent way.  If <code>parent</code> is the empty
    * abstract pathname then the new <code>OWFile</code> instance is created by
    * converting <code>child</code> into an abstract pathname and resolving
    * the result against a system-dependent default directory.  Otherwise each
    * pathname string is converted into an abstract pathname and the child
    * abstract pathname is resolved against the parent.
    *
    * @param   owd    OneWireContainer that this Filesystem resides on
    * @param   parent  The parent abstract pathname
    * @param   child   The child pathname string
    * @throws  NullPointerException
    *          If <code>child</code> is <code>null</code>
    */
   public OWFile(OWFile parent, String child)
   {
      if (child == null)
         throw new NullPointerException("child is null");

      String new_path;

      if (parent.getAbsolutePath().endsWith("/"))
         new_path = parent.getAbsolutePath() + child;
      else
         new_path = parent.getAbsolutePath() + separator + child;

      fd  = new OWFileDescriptor(parent.getOneWireContainers(), new_path);
   }

   //--------
   //-------- Path 'get' Methods
   //--------

   /**
    * 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.
    *
    * @return  The name of the file or directory denoted by this abstract
    *          pathname, or the empty string if this pathname's name sequence
    *          is empty
    */
   public String getName()
   {
      return fd.getName();
   }

   /**
    * Returns the pathname string of this abstract pathname's parent, or
    * <code>null</code> if this pathname does not name a parent directory.
    *
    * <p> The <em>parent</em> 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.
    *
    * @return  The pathname string of the parent directory named by this
    *          abstract pathname, or <code>null</code> if this pathname
    *          does not name a parent
    */
   public String getParent()
   {
      return fd.getParent();
   }

   /**
    * Returns the abstract pathname of this abstract pathname's parent,
    * or <code>null</code> if this pathname does not name a parent
    * directory.