jafs-library-20020725
[openafs.git] / src / JAVA / classes / org / openafs / jafs / AFSFileException.java
1 /*
2  * @(#)AFSFileException.java    2.0 01/04/16
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.util.Locale;
27
28 /**
29  * An exception indicating that a file related error has occured in the 
30  * Java AFS API, in the Java AFS JNI, or in the AFS file system.
31  *
32  * <P> This exception extends Java's <code>java.io.IOException</code>
33  * and is therefore often used as a substitution for
34  * {@link java.io.IOException}.
35  *
36  * @version 2.0, 04/16/2001
37  * @version 1.0, 05/25/2000
38  * @see     AFSException
39  * @see     java.io.IOException
40  */
41 public class AFSFileException extends java.io.IOException
42 {
43   /**
44    * The AFS specific error number (code). 
45    * @see     #getErrorCode()
46    */
47   protected int errno;
48
49   /**
50    * Constructs an <code>AFSFileException</code> with the specified detail
51    * message.
52    *
53    * @param   reason   the detail message.
54    */
55   public AFSFileException (String reason)
56   {
57     super(reason);
58   }
59   /*-----------------------------------------------------------------------*/
60   /**
61    * Returns the AFS specific error number (code).  This code can be interpreted 
62    * by use of the <code>{@link ErrorTable}</code> class method 
63    * <code>{@link ErrorTable#getMessage(int)}</code>.
64    *
65    * @return  the AFS error code of this <code>AFSException</code> 
66    *          object. 
67    * @see     ErrorTable#getMessage(int)
68    */
69   public int getErrorCode() 
70   {
71     return errno;
72   }
73   /*-----------------------------------------------------------------------*/
74   /**
75    * Returns the error message string of this exception.
76    *
77    * @return  the error message string of this exception object. 
78    *            
79    * @see     #getAFSMessage()
80    */
81   public String getMessage()
82   {
83     String msg = super.getMessage();
84     return (msg == null) ? ErrorTable.getMessage(errno) : msg;
85   }
86   /*-----------------------------------------------------------------------*/
87   /**
88    * Returns the locale specific error message string of this exception.
89    *
90    * @return  the error message string of this exception object. 
91    * @param   locale the locale for which this message will be displayed
92    *            
93    * @see     #getAFSMessage()
94    */
95   public String getMessage(Locale locale)
96   {
97     String msg = super.getMessage();
98     return (msg == null) ? ErrorTable.getMessage(errno, locale) : msg;
99   }
100   /**
101    * Constructs an <code>AFSFileException</code> with the specified error
102    * code. This constructor will also generate the appropriate error message
103    * respective to the specified error code. 
104    *
105    * @param   errno    the AFS error number (error code).
106    */
107   public AFSFileException (int errno)
108   {
109     super(ErrorTable.getMessage( (errno == 0) ? ErrorTable.UNKNOWN : errno ));
110     this.errno = (errno == 0) ? ErrorTable.UNKNOWN : errno;
111   }
112   /**
113    * Constructs an <code>AFSFileException</code> with the specified detail
114    * message and specified error code.  In this constructor the specified
115    * detail message overrides the default AFS error message defined by the
116    * <code>ErrorTable</code> class.  Therefore, to retrieve the AFS specific 
117    * error message, you must use the <code>{@link #getAFSMessage}
118    * </code> method. The <code>{@link #getMessage}</code> method will return
119    * the message specified in this constructor.
120    *
121    * @param   reason   the detail message.
122    * @param   errno    the AFS error number (error code).
123    * @see     #getAFSMessage()
124    */
125   public AFSFileException (String reason, int errno)
126   {
127     super( (reason == null) ? ErrorTable.getMessage( errno ) : reason );
128     this.errno = errno;
129   }
130   /*-----------------------------------------------------------------------*/
131   /**
132    * Returns the AFS error message string defined by the <code>ErrorTable
133    * </code> class.  The message will be formatted according to the default
134    * Locale.
135    *
136    * <P> This message is also available from this object's super class
137    * method <code>getMessage</code>. However, this method will always return
138    * the string message associated with the actual AFS error code/number
139    * specified, whereas the {@link #getMessage()} method will return the
140    * string message intended for this Exception object, which may be
141    * an overridden message defined in the constructor of this Exception.
142    *
143    * @return  the AFS error message string of this exception object. 
144    *            
145    * @see     #getAFSMessage(Locale)
146    * @see         AFSFileException#AFSFileException(String, int)
147    * @see     ErrorTable#getMessage(int)
148    * @see     java.lang.Exception#getMessage()
149    */
150   public String getAFSMessage() 
151   {
152     return ErrorTable.getMessage(errno);
153   }
154   /*-----------------------------------------------------------------------*/
155   /**
156    * Returns the AFS error message defined by the <code>ErrorTable</code>
157    * class.  The message will be formatted according to the specified Locale.
158    *
159    * <P> This message is also available from this object's super class
160    * method <code>getMessage</code>. However, this method will always return
161    * the string message associated with the actual AFS error code/number
162    * specified, whereas the {@link #getMessage()} method will return the
163    * string message intended for this Exception object, which may be
164    * an overridden message defined in the constructor of this Exception.
165    *
166    * @return  the AFS error message string of this exception object. 
167    * @param   locale the locale for which this message will be displayed
168    *            
169    * @see     #getAFSMessage()
170    * @see         AFSFileException#AFSFileException(String, int)
171    * @see     ErrorTable#getMessage(int, Locale)
172    * @see     java.lang.Exception#getMessage()
173    */
174   public String getAFSMessage(Locale locale)
175   {
176     return ErrorTable.getMessage(errno, locale);
177   }
178   /*-----------------------------------------------------------------------*/
179   /**
180    * Returns a string representation of this AFS Exception.
181    *
182    * @return  the AFS error message string of this 
183    *          <code>AFSFileException</code> object. 
184    *            
185    * @see     #getMessage()
186    */
187   public String toString()
188   {
189     return "AFSFileException: Error Code: " + errno + "; Message: " +
190             getMessage();
191   }
192   /*-----------------------------------------------------------------------*/
193 }
194
195