src/JAVA/classes/org/openafs/jafs/FileInputStream.java

   1 /*
   2  * @(#)FilterInputStream.java   1.0 00/10/10
   3  *
   4  * Copyright (c) 2001 International Business Machines Corp.
   5  * All rights reserved.
   6  *
   7  * This software has been released under the terms of the IBM Public
   8  * License.  For details, see the LICENSE file in the top-level source
   9  * directory or online at http://www.openafs.org/dl/license10.html
  10  *
  11  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  12  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  13  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  14  * A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR
  15  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  16  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  17  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  18  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  19  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  20  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  21  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  22  */
  23
  24 package org.openafs.jafs;
  25
  26 import java.io.InputStream;
  27
  28 /**
  29  * This class is a file input stream for files within AFS.
  30  * It is an input stream for reading data from a
  31  * <code>{@link org.openafs.jafs.File}</code>.
  32  *
  33  * @version 2.1, 08/03/2001
  34  * @see org.openafs.jafs.File
  35  * @see org.openafs.jafs.FileOutputStream
  36  * @see java.io.FileInputStream
  37  */
  38 public class FileInputStream extends InputStream
  39 {
  40   /** Status indicator for the current state of this file input stream */
  41   private int fileDescriptor;
  42
  43   /**
  44    * Creates a <code>FileInputStream</code> by
  45    * opening a connection to an actual AFS file,
  46    * the file named by the path name <code>name</code>
  47    * in the AFS file system.
  48    *
  49    * @param name the name of the file to read from
  50    * @exception AFSFileException  If an AFS specific error occurs,
  51    *                    if the file does not, or cannot be opened for any
  52    *                    other reason, including authorization.
  53    */
  54   public FileInputStream(String name) throws AFSFileException
  55   {
  56     this.fileDescriptor = this.openReadOnly(name);
  57   }
  58   /**
  59    * Creates a <code>FileInputStream</code> by
  60    * opening a connection to an actual AFS file,
  61    * the file represented by file <code>file</code>
  62    * in the AFS file system.
  63    *
  64    * @param file        an AFS file object representing a file to read from
  65    * @exception AFSFileException  If an AFS specific error occurs,
  66    *                    if the file does not, or cannot be opened for any
  67    *                    other reason, including authorization.
  68    */
  69   public FileInputStream(File file) throws AFSFileException
  70   {
  71     this(file.getPath());
  72   }
  73
  74   /*-------------------------------------------------------------------------*/
  75
  76   /**
  77    * Reads the next byte of data from this input stream. The value
  78    * byte is returned as an <code>int</code> in the range
  79    * <code>0</code> to <code>255</code>. If no byte is available
  80    * because the end of the stream has been reached, the value
  81    * <code>-1</code> is returned. This method blocks until input data
  82    * is available, the end of the stream is detected, or an exception
  83    * is thrown.
  84    *
  85    * <p>This method simply performs <code>in.read()</code> and returns
  86    * the result.
  87    *
  88    * @return   the next byte of data, or <code>-1</code> if the end of the
  89    *           stream is reached.
  90    * @exception  AFSFileException  if an I/O or other file related error occurs.
  91    * @see        java.io.FileInputStream#read
  92    */
  93   public int read() throws AFSFileException
  94   {
  95     byte[] bytes = new byte[1];
  96     this.read(bytes, 0, 1);
  97     return bytes[0];
  98   }
  99   /**
 100    * Reads up to <code>b.length</code> bytes of data from this input
 101    * stream into an array of bytes. This method blocks until some input
 102    * is available.
 103    *
 104    * @param      b   the buffer into which the data is read.
 105    * @return     the total number of bytes read into the buffer, or
 106    *             <code>-1</code> if there is no more data because the end of
 107    *             the file has been reached.
 108    * @exception  AFSFileException  if an I/O or other file related error occurs.
 109    */
 110   public int read(byte[] b) throws AFSFileException
 111   {
 112     return this.read(b, 0, b.length);
 113   }
 114
 115   /////////////// public native methods ////////////////////
 116
 117   /**
 118    * Reads up to <code>len</code> bytes of data from this input stream
 119    * into an array of bytes. This method blocks until some input is
 120    * available.
 121    *
 122    * @param      b     the buffer into which the data is read.
 123    * @param      off   the start offset of the data.
 124    * @param      len   the maximum number of bytes read.
 125    * @return     the total number of bytes read into the buffer, or
 126    *             <code>-1</code> if there is no more data because the end of
 127    *             the file has been reached.
 128    * @exception  AFSFileException  if an I/O or other file related error occurs.
 129    */
 130   public native int read(byte[] b, int off, int len) throws AFSFileException;
 131   /**
 132    * Skips over and discards <code>n</code> bytes of data from the
 133    * input stream. The <code>skip</code> method may, for a variety of
 134    * reasons, end up skipping over some smaller number of bytes,
 135    * possibly <code>0</code>. The actual number of bytes skipped is returned.
 136    *
 137    * @param      n   the number of bytes to be skipped.
 138    * @return     the actual number of bytes skipped.
 139    * @exception  AFSFileException  if an I/O or other file related error occurs.
 140    */
 141   public native long skip(long n) throws AFSFileException;
 142   /**
 143    * Closes this file input stream and releases any system resources
 144    * associated with the stream.
 145    *
 146    * @exception  AFSFileException  if an I/O or other file related error occurs.
 147    */
 148   public native void close() throws AFSFileException;
 149
 150   /////////////// private native methods ////////////////////
 151
 152   /**
 153    * Opens the specified AFS file for reading.
 154    *
 155    * @param name fileName of file to be opened
 156    * @return    file descriptor
 157    * @exception  AFSFileException  if an I/O or other file related error occurs.
 158    */
 159   private native int openReadOnly(String fileName) throws AFSFileException;
 160
 161   /*-------------------------------------------------------------------------*/
 162 }
 163
 164
 165
 166
 167