jafs-library-20020725
[openafs.git] / src / JAVA / classes / org / openafs / jafs / FileOutputStream.java
1 /*
2  * @(#)FilterOutputStream.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.OutputStream;
27
28 /**
29  * This class is a file output stream for files within AFS.  
30  * It is an output stream for writing data to 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.FileInputStream
36  * @see java.io.FileOutputStream
37  */
38 public class FileOutputStream extends OutputStream 
39 {
40   /** Status indicator for the current state of this file output stream */
41   private int fileDescriptor;
42
43   /**
44    * Creates an output file stream to write to the AFS file with the 
45    * specified name.
46    * <p>
47    * If the file exists but is a directory rather than a regular file, does
48    * not exist but cannot be created, or cannot be opened for any other
49    * reason then a <code>AFSFileException</code> is thrown.
50    *
51    * @param name the name of the file to write to
52    * @exception AFSFileException  If an AFS specific error occurs, 
53    *                    if the file exists but is a directory
54    *                    rather than a regular file, does not exist but cannot
55    *                    be created, or cannot be opened for any other reason, including
56    *                    authorization.
57    */
58   public FileOutputStream(String name) throws AFSFileException
59   {
60     this(name, false);
61   }
62   /**
63    * Creates an output file stream to write to the AFS file with the specified
64    * <code>name</code>.  If the second argument is <code>true</code>, then
65    * bytes will be written to the end of the file rather than the beginning.
66    * <p>
67    * If the file exists but is a directory rather than a regular file, does
68    * not exist but cannot be created, or cannot be opened for any other
69    * reason then a <code>AFSFileException</code> is thrown.
70    * 
71    * @param     name            the name of the file to write to
72    * @param     append  if <code>true</code>, then bytes will be written
73    *                            to the end of the file rather than the beginning
74    * @exception AFSFileException  If an AFS specific error occurs, 
75    *                    if the file exists but is a directory
76    *                    rather than a regular file, does not exist but cannot
77    *                    be created, or cannot be opened for any other reason, including
78    *                    authorization.
79    */
80   public FileOutputStream(String name, boolean append) throws AFSFileException
81   {
82     if (append) {
83       fileDescriptor = this.openAppend(name);
84     } else {
85       fileDescriptor = this.openWrite(name);
86     }
87   }
88   /**
89    * Creates a file output stream to write to the AFS file represented by 
90    * the specified <code>File</code> object.
91    * <p>
92    * If the file exists but is a directory rather than a regular file, does
93    * not exist but cannot be created, or cannot be opened for any other
94    * reason then a <code>AFSFileException</code> is thrown.
95    *
96    * @param    file         the AFS file to be opened for writing.
97    * @exception AFSFileException  If an AFS specific error occurs, 
98    *                    if the file exists but is a directory
99    *                    rather than a regular file, does not exist but cannot
100    *                    be created, or cannot be opened for any other reason, including
101    *                    authorization.
102    * @see    org.openafs.jafs.File#getPath()
103    */
104   public FileOutputStream(File file) throws AFSFileException
105   {
106     this(file.getPath(), false);
107   }
108   /**
109    * Creates a file output stream to write to the AFS file represented by 
110    * the specified <code>File</code> object.
111    * <p>
112    * If the file exists but is a directory rather than a regular file, does
113    * not exist but cannot be created, or cannot be opened for any other
114    * reason then a <code>AFSFileException</code> is thrown.
115    *
116    * @param file                the AFS file to be opened for writing.
117    * @param     append  if <code>true</code>, then bytes will be written
118    *                            to the end of the file rather than the beginning
119    * @exception AFSFileException  If an AFS specific error occurs, 
120    *                    if the file exists but is a directory
121    *                    rather than a regular file, does not exist but cannot
122    *                    be created, or cannot be opened for any other reason, including
123    *                    authorization.
124    * @see    org.openafs.jafs.File#getPath()
125    */
126   public FileOutputStream(File file, boolean append) throws AFSFileException
127   {
128     this(file.getPath(), append);
129   }
130
131   /*-------------------------------------------------------------------------*/
132
133   /**
134    * Writes the specified <code>byte</code> to this file output stream. 
135    * <p>
136    * Implements the abstract <tt>write</tt> method of <tt>OutputStream</tt>. 
137    *
138    * @param      b   the byte to be written.
139    * @exception  AFSFileException  if an error occurs.
140    */
141   public void write(int b) throws AFSFileException 
142   {
143     byte[] bytes = new byte[1];
144     bytes[0] = (byte) b;
145     this.write(bytes, 0, 1);
146   }
147   /**
148    * Writes <code>b.length</code> bytes from the specified byte array 
149    * to this file output stream. 
150    * <p>
151    * Implements the <code>write</code> method of three arguments with the 
152    * arguments <code>b</code>, <code>0</code>, and 
153    * <code>b.length</code>. 
154    * <p>
155    * Note that this method does not call the one-argument 
156    * <code>write</code> method of its underlying stream with the single 
157    * argument <code>b</code>. 
158    *
159    * @param    b   the data to be written.
160    * @exception  AFSFileException  if an error occurs.
161    * @see    #write(byte[], int, int)
162    * @see    java.io.FilterOutputStream#write(byte[], int, int)
163    */
164   public void write(byte[] b) throws AFSFileException 
165   {
166     this.write(b, 0, b.length);
167   }
168
169   /////////////// public native methods ////////////////////
170
171   /**
172    * Writes <code>len</code> bytes from the specified 
173    * <code>byte</code> array starting at offset <code>off</code> to 
174    * this file output stream. 
175    *
176    * @param b the data to be written
177    * @param off the start offset in the data
178    * @param len the number of bytes that are written
179    * @exception  AFSFileException  if an I/O or other file related error occurs.
180    * @see    java.io.FilterOutputStream#write(int)
181    */
182   public native void write(byte[] b, int off, int len) throws AFSFileException;
183   /**
184    * Closes this file output stream and releases any system resources 
185    * associated with this stream. This file output stream may no longer 
186    * be used for writing bytes. 
187    *
188    * @exception  AFSFileException  if an I/O or other file related error occurs.
189    */
190   public native void close()  throws AFSFileException;
191
192   /////////////// private native methods ////////////////////
193
194   /**
195    * Opens an AFS file, with the specified name, for writing.
196    *
197    * @param             filename name of file to be opened
198    * @return    file descriptor
199    * @exception  AFSFileException  if an I/O or other file related error occurs.
200    */
201   private native int openWrite(String filename) throws AFSFileException;
202   /**
203    * Opens an AFS file, with the specified name, for appending.
204    *
205    * @param             filename name of file to be opened
206    * @return    file descriptor
207    * @exception  AFSFileException  if an I/O or other file related error occurs.
208    */
209   private native int openAppend(String filename) throws AFSFileException;
210
211   /*-------------------------------------------------------------------------*/
212 }
213
214
215
216
217