Java provides a way for methods to indicate when they cannot complete normally through an exception-handling mechanism.
Exceptions are objects of a type that is a subtype of Throwable. Throwing an exception causes the control flow of the executing code to jump to a point where the exception can be handled, unwinding the call stack as it goes.
To handle an exception, it is necessary to declare a try block with one or more catch clauses. A catch clause declares a variable with a type that is an exception.
Any exception object propagated to the try block that can be assigned to the variable in a catch clause is caught by this clause.
/**
* Copyright (C) 2024 by Martin Robillard.
* See https://codesample.info/about.html
*/
package essentials;
import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
public class ExceptionHandling
{
public static void main(String[] args)
{
try
{
;
}
catch (NullPointerException nullPointerException)
{
nullPointerException.printStackTrace();
}
catch (IOException ioException)
{
System.out.println("Caught an IOException with message: "
+ );
}
{
System.out.println("This code always executes");
}
throwsUnchecked();
/*
* The code below will not execute because the call to throwsUnchecked()
* results in an exception propagating out of the main method. To try
* our the method, you can switch the calls throwsUnchecked() and
* throwsExplicit(null);
*/
throwsExplicit(null);
}
/*
* This method an unchecked (runtime) exception of type
* NumberFormatException.
*/
public static void
{
Integer.parseInt("Not a number");
}
/*
* This method throws a checked exception.
*/
public static void throwsChecked()
{
Files.(Path.of("NONEXISTENT FILE"));
}
/*
* This method explicitly throws an IllegalStateException
*/
public static void throwsExplicit(String message)
{
if( message == null )
{
new ;
}
System.out.println(message);
}
}This method does not explicitly throw an exception (using the throws keyword), but an exception
thrown in a method that it calls will propagate out of it. Except when
the distinction matters, we can say that the method "throws" an exception
in both of these scenarios.
This method does not explicitly throw an exception (using the throws keyword), but an exception
thrown in a method that it calls will propagate out of it. Except when
the distinction matters, we can say that the method "throws" an exception
in both of these scenarios.
A finally block allows us to
specify code that always executes after its try block, even if exceptions are raised within it.
A finally block allows us to
specify code that always executes after its try block, even if exceptions are raised within it.
This method is guaranteed to throw an NumberFormatException by design (and
for illustration purposes), because the parseInt method aims to interpret the
argument as an integer, which will obviously not work here. The methods's Javadocs
document the case.
This method is guaranteed to throw an NumberFormatException by design (and
for illustration purposes), because the parseInt method aims to interpret the
argument as an integer, which will obviously not work here. The methods's Javadocs
document the case.
The throw statement explicitly and immediately throws the object that results from evaluating the expression to the right
of the throw keyword. Although it is very common to create a new exception object in this situation, it does not have to be
so: it is also possible to throw an exception referenced in a variable, or obtained in any other way.
The throw statement explicitly and immediately throws the object that results from evaluating the expression to the right
of the throw keyword. Although it is very common to create a new exception object in this situation, it does not have to be
so: it is also possible to throw an exception referenced in a variable, or obtained in any other way.
The throwsChecked method to throw a . For this reason,
the compiler will require client code to either catch the exception (as is done here)
or redeclare it in the signature of the method (here the main method).
The throwsChecked method to throw a . For this reason,
the compiler will require client code to either catch the exception (as is done here)
or redeclare it in the signature of the method (here the main method).
Exceptions thrown by a method are supplied after the argument list in the method
declaration, for example:
public static void throwsChecked() throws IOException
Exceptions thrown by a method are supplied after the argument list in the method
declaration, for example:
public static void throwsChecked() throws IOException
An exception whose propagation must be documented in the code, and is checked by
the compiler. Exception types that are subtypes of Exception
but not subtypes of RuntimeException are checked.
Exceptions that are subtypes of RuntimeException are unchecked.
An exception whose propagation must be documented in the code, and is checked by
the compiler. Exception types that are subtypes of Exception
but not subtypes of RuntimeException are checked.
Exceptions that are subtypes of RuntimeException are unchecked.
NullPointerExceptions are usually indicative of a bug in the code. They are unchecked exceptions,
and catching them is of questionable benefit. Here the clause is provided to illustrate how multiple
catch clauses can be attached to a try block. In practice, this clause would catch any null pointer
exception that propagates out of throwsChecked().
NullPointerExceptions are usually indicative of a bug in the code. They are unchecked exceptions,
and catching them is of questionable benefit. Here the clause is provided to illustrate how multiple
catch clauses can be attached to a try block. In practice, this clause would catch any null pointer
exception that propagates out of throwsChecked().
This catch clause is required because throwsChecked() declares to throw an IOExceptions,
which is a type of checked exception. The one alternative to providing a catch clause is to
instead add throws IOException to the signature of the main method.
This catch clause is required because throwsChecked() declares to throw an IOExceptions,
which is a type of checked exception. The one alternative to providing a catch clause is to
instead add throws IOException to the signature of the main method.
Calling this method will cause a NumberFormatException to propagate out of the method call.
Because the exception is not caught in any catch clause, the execution of the main method will
terminate immediately and instead propagate the exception to the calling context, which in this case
is the Java Virtual Machine.
Calling this method will cause a NumberFormatException to propagate out of the method call.
Because the exception is not caught in any catch clause, the execution of the main method will
terminate immediately and instead propagate the exception to the calling context, which in this case
is the Java Virtual Machine.
Unchecked exceptions that can propagate out of a method do not need to be declared in the method's signature. It is technically possible to declare them anyways, but the compiler will not check whether the information is accurate (i.e., whether exceptions of this type can actually be thrown by the method).
Unchecked exceptions that can propagate out of a method do not need to be declared in the method's signature. It is technically possible to declare them anyways, but the compiler will not check whether the information is accurate (i.e., whether exceptions of this type can actually be thrown by the method).
This code illustrates that Java exceptions are regular objects, on which we can call methods.
This code illustrates that Java exceptions are regular objects, on which we can call methods.
Throwable instance (which may be null).
This methods declares to throw exceptions of type IOException, which is checked. Client methods
will need to either catch this exception or redeclare it in their own signature.
This methods declares to throw exceptions of type IOException, which is checked. Client methods
will need to either catch this exception or redeclare it in their own signature.
The declaration of this method
includes throws IOException. Because IOException is checked, it needs to be either caught or re-declared.
The declaration of this method
includes throws IOException. Because IOException is checked, it needs to be either caught or re-declared.
The options array may be used to indicate how symbolic links are handled for the case that the file is a symbolic link. By default, symbolic links are followed and the file attribute of the final target of the link is read. If the option NOFOLLOW_LINKS is present then symbolic links are not followed.
path - the path to the file
options - options indicating how symbolic links are handled
FileTime representing the time the file was last modified, or an implementation specific default when a time stamp to indicate the time of last modification is not supported by the file system
IOException - if an I/O error occurs
SecurityException - In the case of the default provider, and a security manager is installed, its checkRead method denies read access to the file.
An for any other class, exception classes have constructors. A very common constructor for exceptions takes a message string as argument. See the Javadocs of exception types for alternatives.
IllegalArgumentException with the specified detail message.
An for any other class, exception classes have constructors. A very common constructor for exceptions takes a message string as argument. See the Javadocs of exception types for alternatives.
IllegalArgumentException with the specified detail message.
s - the detail message.
Throwable object on the error output stream that is the value of the field System.err. The first line of output contains the result of the toString() method for this object. Remaining lines represent data previously recorded by the method fillInStackTrace(). The format of this information depends on the implementation, but the following example may be regarded as typical:
Throwable object on the error output stream that is the value of the field System.err. The first line of output contains the result of the toString() method for this object. Remaining lines represent data previously recorded by the method fillInStackTrace(). The format of this information depends on the implementation, but the following example may be regarded as typical:
java.lang.NullPointerException
at MyClass.mash(MyClass.java:9)
at MyClass.crunch(MyClass.java:6)
at MyClass.main(MyClass.java:3)
This example was produced by running the program:
class MyClass {
public static void main(String[] args) {
crunch(null);
}
static void crunch(int[] a) {
mash(a);
}
static void mash(int[] b) {
System.out.println(b[0]);
}
}
The backtrace for a throwable with an initialized, non-null cause should generally include the backtrace for the cause. The format of this information depends on the implementation, but the following example may be regarded as typical:
HighLevelException: MidLevelException: LowLevelException
at Junk.a(Junk.java:13)
at Junk.main(Junk.java:4)
Caused by: MidLevelException: LowLevelException
at Junk.c(Junk.java:23)
at Junk.b(Junk.java:17)
at Junk.a(Junk.java:11)
... 1 more
Caused by: LowLevelException
at Junk.e(Junk.java:30)
at Junk.d(Junk.java:27)
at Junk.c(Junk.java:21)
... 3 more
Note the presence of lines containing the characters "...". These lines indicate that the remainder of the stack trace for this exception matches the indicated number of frames from the bottom of the stack trace of the exception that was caused by this exception (the "enclosing" exception). This shorthand can greatly reduce the length of the output in the common case where a wrapped exception is thrown from the same method as the "causative exception" is caught. The above example was produced by running the program:
public class Junk {
public static void main(String args[]) {
try {
a();
} catch(HighLevelException e) {
e.printStackTrace();
}
}
static void a() throws HighLevelException {
try {
b();
} catch(MidLevelException e) {
throw new HighLevelException(e);
}
}
static void b() throws MidLevelException {
c();
}
static void c() throws MidLevelException {
try {
d();
} catch(LowLevelException e) {
throw new MidLevelException(e);
}
}
static void d() throws LowLevelException {
e();
}
static void e() throws LowLevelException {
throw new LowLevelException();
}
}
class HighLevelException extends Exception {
HighLevelException(Throwable cause) { super(cause); }
}
class MidLevelException extends Exception {
MidLevelException(Throwable cause) { super(cause); }
}
class LowLevelException extends Exception {
}
As of release 7, the platform supports the notion of suppressed exceptions (in conjunction with the try-with-resources statement). Any exceptions that were suppressed in order to deliver an exception are printed out beneath the stack trace. The format of this information depends on the implementation, but the following example may be regarded as typical:
Exception in thread "main" java.lang.Exception: Something happened
at Foo.bar(Foo.java:10)
at Foo.main(Foo.java:5)
Suppressed: Resource$CloseFailException: Resource ID = 0
at Resource.close(Resource.java:26)
at Foo.bar(Foo.java:9)
... 1 more
Note that the "... n more" notation is used on suppressed exceptions just as it is used on causes. Unlike causes, suppressed exceptions are indented beyond their "containing exceptions."
An exception can have both a cause and one or more suppressed exceptions:
Exception in thread "main" java.lang.Exception: Main block
at Foo3.main(Foo3.java:7)
Suppressed: Resource$CloseFailException: Resource ID = 2
at Resource.close(Resource.java:26)
at Foo3.main(Foo3.java:5)
Suppressed: Resource$CloseFailException: Resource ID = 1
at Resource.close(Resource.java:26)
at Foo3.main(Foo3.java:5)
Caused by: java.lang.Exception: I did it
at Foo3.main(Foo3.java:8)
Likewise, a suppressed exception can have a cause:
Exception in thread "main" java.lang.Exception: Main block
at Foo4.main(Foo4.java:6)
Suppressed: Resource2$CloseFailException: Resource ID = 1
at Resource2.close(Resource2.java:20)
at Foo4.main(Foo4.java:5)
Caused by: java.lang.Exception: Rats, you caught me
at Resource2$CloseFailException.<init>(Resource2.java:45)
... 2 more
null in a case where an object is required. These include:
null in a case where an object is required. These include:
null object. null object. null as if it were an array. null as if it were an array. null as if it were a Throwable value. Applications should throw instances of this class to indicate other illegal uses of the null object. NullPointerException objects may be constructed by the virtual machine as if suppression were disabled and/or the stack trace was not writable.
A Path represents a path that is hierarchical and composed of a sequence of directory and file name elements separated by a special separator or delimiter. A root component, that identifies a file system hierarchy, may also be present. The name element that is farthest from the root of the directory hierarchy is the name of a file or directory. The other name elements are directory names. A Path can represent a root, a root and a sequence of names, or simply one or more name elements. A Path is considered to be an empty path if it consists solely of one name element that is empty. Accessing a file using an empty path is equivalent to accessing the default directory of the file system. Path defines the getFileName, getParent, getRoot, and subpath methods to access the path components or a subsequence of its name elements.
In addition to accessing the components of a path, a Path also defines the resolve and resolveSibling methods to combine paths. The relativize method that can be used to construct a relative path between two paths. Paths can be compared, and tested against each other using the startsWith and endsWith methods.
This interface extends Watchable interface so that a directory located by a path can be registered with a WatchService and entries in the directory watched.
WARNING: This interface is only intended to be implemented by those developing custom file system implementations. Methods may be added to this interface in future releases.
Paths may be used with the Files class to operate on files, directories, and other types of files. For example, suppose we want a BufferedReader to read text from a file "access.log". The file is located in a directory "logs" relative to the current working directory and is UTF-8 encoded.
Path path = FileSystems.getDefault().getPath("logs", "access.log");
BufferedReader reader = Files.newBufferedReader(path, StandardCharsets.UTF_8);
Paths associated with the default provider are generally interoperable with the java.io.File class. Paths created by other providers are unlikely to be interoperable with the abstract path names represented by java.io.File. The toPath method may be used to obtain a Path from the abstract path name represented by a java.io.File object. The resulting Path can be used to operate on the same file as the java.io.File object. In addition, the toFile method is useful to construct a File from the String representation of a Path.
Implementations of this interface are immutable and safe for use by multiple concurrent threads.
Path by converting a path string, or a sequence of strings that when joined form a path string. If more does not specify any elements then the value of the first parameter is the path string to convert. If more specifies one or more elements then each non-empty string, including first, is considered to be a sequence of name elements and is joined to form a path string. The details as to how the Strings are joined is provider specific but typically they will be joined using the name-separator as the separator. For example, if the name separator is "/" and getPath("/foo","bar","gus") is invoked, then the path string "/foo/bar/gus" is converted to a Path. A Path representing an empty path is returned if first is the empty string and more does not contain any non-empty strings.
Path by converting a path string, or a sequence of strings that when joined form a path string. If more does not specify any elements then the value of the first parameter is the path string to convert. If more specifies one or more elements then each non-empty string, including first, is considered to be a sequence of name elements and is joined to form a path string. The details as to how the Strings are joined is provider specific but typically they will be joined using the name-separator as the separator. For example, if the name separator is "/" and getPath("/foo","bar","gus") is invoked, then the path string "/foo/bar/gus" is converted to a Path. A Path representing an empty path is returned if first is the empty string and more does not contain any non-empty strings.
The Path is obtained by invoking the getPath method of the default FileSystem.
Note that while this method is very convenient, using it will imply an assumed reference to the default FileSystem and limit the utility of the calling code. Hence it should not be used in library code intended for flexible reuse. A more flexible alternative is to use an existing Path instance as an anchor, such as:
Path dir = ...
Path path = dir.resolve("file");
first - the path string or initial part of the path string
more - additional strings to be joined to form the path string
Path
InvalidPathException - if the path string cannot be converted to a Path
In most cases, the methods defined here will delegate to the associated file system provider to perform the file operations.
System class contains several useful class fields and methods. It cannot be instantiated. Among the facilities provided by the System class are standard input, standard output, and error output streams; access to externally defined properties and environment variables; a means of loading files and libraries; and a utility method for quickly copying a portion of an array.
System class contains several useful class fields and methods. It cannot be instantiated. Among the facilities provided by the System class are standard input, standard output, and error output streams; access to externally defined properties and environment variables; a means of loading files and libraries; and a utility method for quickly copying a portion of an array.
Console.charset() if the Console exists, stdout.encoding otherwise.
Console.charset() if the Console exists, stdout.encoding otherwise.
For simple stand-alone Java applications, a typical way to write a line of output data is:
System.out.println(data)
See the println methods in class PrintStream.
print(String) and then println().
print(String) and then println().
x - The String to be printed.
String class represents character strings. All string literals in Java programs, such as "abc", are implemented as instances of this class.
String class represents character strings. All string literals in Java programs, such as "abc", are implemented as instances of this class.
Strings are constant; their values cannot be changed after they are created. String buffers support mutable strings. Because String objects are immutable they can be shared. For example:
String str = "abc";
is equivalent to:
char data[] = {'a', 'b', 'c'};
String str = new String(data);
Here are some more examples of how strings can be used:
System.out.println("abc");
String cde = "cde";
System.out.println("abc" + cde);
String c = "abc".substring(2, 3);
String d = cde.substring(1, 2);
The class String includes methods for examining individual characters of the sequence, for comparing strings, for searching strings, for extracting substrings, and for creating a copy of a string with all characters translated to uppercase or to lowercase. Case mapping is based on the Unicode Standard version specified by the Character class.
The Java language provides special support for the string concatenation operator ( + ), and for conversion of other objects to strings. For additional information on string concatenation and conversion, see The Java Language Specification.
Unless otherwise noted, passing a null argument to a constructor or method in this class will cause a NullPointerException to be thrown.
A String represents a string in the UTF-16 format in which supplementary characters are represented by surrogate pairs (see the section Unicode Character Representations in the Character class for more information). Index values refer to char code units, so a supplementary character uses two positions in a String.
The String class provides methods for dealing with Unicode code points (i.e., characters), in addition to those for dealing with Unicode code units (i.e., char values).
Unless otherwise noted, methods for comparing Strings do not take locale into account. The Collator class provides methods for finer-grain, locale-sensitive String comparison.
javac compiler may implement the operator with StringBuffer, StringBuilder, or java.lang.invoke.StringConcatFactory depending on the JDK version. The implementation of string conversion is typically through the method toString, defined by Object and inherited by all classes in Java.
Integer class wraps a value of the primitive type int in an object. An object of type Integer contains a single field whose type is int.
Integer class wraps a value of the primitive type int in an object. An object of type Integer contains a single field whose type is int.
In addition, this class provides several methods for converting an int to a String and a String to an int, as well as other constants and methods useful when dealing with an int.
This is a value-based class; programmers should treat instances that are equal as interchangeable and should not use instances for synchronization, or unpredictable behavior may occur. For example, in a future release, synchronization may fail.
Implementation note: The implementations of the "bit twiddling" methods (such as highestOneBit and numberOfTrailingZeros) are based on material from Henry S. Warren, Jr.'s Hacker's Delight, (Addison Wesley, 2002).
'-' ('\u002D') to indicate a negative value or an ASCII plus sign '+' ('\u002B') to indicate a positive value. The resulting integer value is returned, exactly as if the argument and the radix 10 were given as arguments to the parseInt(java.lang.String, int) method.
'-' ('\u002D') to indicate a negative value or an ASCII plus sign '+' ('\u002B') to indicate a positive value. The resulting integer value is returned, exactly as if the argument and the radix 10 were given as arguments to the parseInt(java.lang.String, int) method.
s - a String containing the int representation to be parsed
NumberFormatException - if the string does not contain a parsable integer.