jafs-library-20020725
[openafs.git] / 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