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