Scanner and console applications

Every program you have written so far has done all the talking. It prints, it computes, it prints again, and it never once stops to ask you anything. Many real tools hold a conversation instead: they ask, you answer, they react. This lesson gives your programs ears, so they can read what a person types at the keyboard.

From a monologue to a conversation#

Until now, output went out through System.out. There is a matching door for input called System.in. Think of System.out as the program's mouth and System.in as its ear. On its own, System.in is awkward to use: it hands over raw bytes, one at a time, with no idea of numbers or words. The Scanner class wraps it and does that work for you, reading a whole number, a word or a line at a time.

A Scanner is an object. String lives in java.lang, which every program can use without an import, but Scanner lives in the package java.util, so you import it first, as you saw in packages and imports.

Read it from top to bottom. The import line brings the name Scanner into scope so you can write it plainly. Then new Scanner(System.in) builds a scanner and points it at the keyboard. After that, sc.nextLine() waits until the person types something and presses Enter. Whatever they typed comes back as a String, which the program stores in name and then prints. Run it, then put your own name in the box and run it again.

The reading methods, one job each#

A scanner has a small family of read methods, and each one reads a different shape of input. Picking the right one is most of the skill. These are the four you will use most:

• nextInt() reads the next whole number and gives you an int.
• nextDouble() reads the next number that may have a decimal point and gives you a double.
• next() reads a single token: one run of non-space characters, one word.
• nextLine() reads everything up to the end of the current line, spaces and all.

A scanner splits what you type into pieces at the whitespace: spaces, tabs and line breaks. Each piece is a token. If you type red green blue, that is three tokens. next() takes exactly one of them and stops at the space. nextLine() takes the rest of the line as one string, spaces included.

The person typed three words, but next() kept only the first, red. The scanner keeps typed text that has not been read yet in its input buffer, and green blue is still sitting there, waiting for a read call that never comes. That leftover is harmless here. Later on this page, leftover text in the buffer is the cause of the most common Scanner bug.

A first interactive program#

Here is a program that asks two questions and reacts. It asks for a name and an age, then greets the person and says how old they will be next year. Almost every console tool has this shape: prompt, read, prompt, read, then compute and respond.

Follow the conversation. The program prints the first prompt and reads. The first line of input is Aisha, so next() returns "Aisha". The program prints the second prompt and reads again. The next line is 20, so nextInt() returns the int 20. With both values in hand, it adds one and prints the greeting. Because age is a real int, the + 1 is arithmetic, not joining text.

When the input is not a number#

People make typos. Suppose someone types twenty at the How old are you? prompt. nextInt() cannot turn twenty into an int, so it throws an exception, the kind of error report you met in reading errors and debugging, and the program stops.

The program stops on line 8 with an InputMismatchException: the next token did not match the type the program asked for. The last line of the report, at Main.main(Main.java:8), points at the line that asked for the number. In a terminal, Java's report also lists a few lines from inside the Scanner class itself, above that one.

Now change the input to 3000000000 and run it again. That token looks like a whole number, but it is too big for an int, so this time the report adds the detail For input string: "3000000000".

Check before you read: hasNextInt#

A scanner can look at the next token without reading it. hasNextInt() answers one question: is the next token a whole number? It returns true or false and leaves the token where it is. That makes a loop that keeps asking until the answer is usable:

With this input the loop body runs twice. twenty is not a whole number, so the loop throws it away with next() and asks again. Neither is 20.5. Then 20 arrives, hasNextInt() returns true, the loop ends, and nextInt() reads it. The next() inside the loop matters: hasNextInt() never moves past a token, so without it the loop would look at twenty forever.

Its relatives work the same way. hasNextDouble() checks for a number that may have a decimal point, hasNext() checks for any token at all, and hasNextLine() checks for another line. Each one answers yes or no and reads nothing.

The classic trap: nextInt then nextLine#

Here is the most common bug a beginner hits with Scanner, and almost everyone hits it once. You read a number, then want to read a full line of text afterward. The obvious code looks right and is wrong.

Run it and look at the console. The program never gave the person a chance to type a name. It printed the second prompt and then the greeting straight away, with fullName empty: the two quote marks have nothing between them. The second line of input, Aisha Khan, was never read. Step through it and stop on line 11, where the narration says what happened.

The first nextLine() gets the empty rest of the line that held 3. The second one starts on a fresh line and gets blue pens. So the output is 3 [] [blue pens], and that extra call is exactly the fix.

The fix: eat the leftover line break#

The cure is one extra line. After the nextInt(), call sc.nextLine() once on its own and ignore what it returns. That spare call swallows the stranded line break, so the next nextLine() starts at the beginning of a fresh line.

One throwaway sc.nextLine() between the number read and the line read is the whole fix. The name has a space in it, so nextLine() was the right tool, and with the leftover line break gone it captures Aisha Khan in full.

Key idea

Reading a number with nextInt or nextDouble leaves the Enter line break in the buffer. If a nextLine comes next, add a throwaway sc.nextLine() between them to clear it.

The other fix: read only whole lines#

The second way out is to never mix the two kinds of read. Read every answer as a whole line with nextLine(), and turn the lines that hold numbers into numbers yourself with Integer.parseInt. Each nextLine() takes its whole line, line break included, so nothing is ever left behind.

The trim() removes any spaces around the number before it is parsed, because parseInt refuses a space in front of the digits.

1import java.util.Scanner;
2 
3public class Main {
4    public static void main(String[] args) {
5        Scanner sc = new Scanner(System.in);
6        int quantity = sc.nextInt();
7        // TODO: the product name comes out empty. Fix it.
8        String product = sc.nextLine();
9        System.out.println(quantity + " x " + product);
10    }
11}

Reading in a loop until a sentinel#

One read is a single question. A real tool keeps asking until you are done. The usual pattern is to read over and over inside a loop, and stop when the person types a special agreed value that means “I am finished”. That value is called a sentinel, like a guard standing at the exit.

The program below keeps reading numbers and adding them to a running total. The sentinel is 0. As soon as the person types 0, the loop ends and the program reports the sum. Every other number goes into the total.

Walk through the run with the code beside it. The program reads one number before the loop, called the priming read, so the while condition has something to test. The first number is 5, which is not 0, so the loop body runs: it adds 5 to total, prompts, and reads again. The same happens for 12 and 3. Then 0 arrives: the condition n != 0 is now false, the loop stops, and the program prints the sum of 5, 12 and 3, which is Total: 20. The sentinel itself is never added, because the program reads it, tests it, and leaves before adding.

1. 1Read once before the loop. This is the priming read that gives the condition a value to check.
2. 2While the value is not the sentinel, do the work, then read the next value at the bottom of the loop.
3. 3When the sentinel arrives, the condition fails and the loop ends without processing it.

Key idea

A sentinel loop reads once before the loop and again at the end of every pass, so the condition always tests the newest value and the sentinel itself is never processed.

Stop when the input runs out#

Sometimes there is no sentinel at all, and the program reads until there is nothing left. hasNextInt() returns false at the end of the input, and also when the next token is not a whole number, so it makes a natural loop condition:

This prints 3 numbers, total 20. The input has 5 and 12 on one line and 3 on the next, and that makes no difference, because nextInt() skips spaces and line breaks alike. On this page the input ends where the box ends. In a terminal, the person signals the end by pressing Ctrl+D on macOS and Linux, or Ctrl+Z and then Enter on Windows. A file always has an end, and the next lesson reads files with this same kind of loop.

1import java.util.Scanner;
2 
3public class Main {
4    public static void main(String[] args) {
5        Scanner sc = new Scanner(System.in);
6        int highest = 0;
7        // TODO: read every score until the input runs out,
8        // and keep the biggest one in highest
9 
10        System.out.println("Highest: " + highest);
11    }
12}

Putting it together: a tiny menu#

Here is the shape of a complete little console app: a loop, a sentinel, and a branch on what was typed. It reads a command word each time and acts on it, stopping when the person types quit. Every entry is a single word read with next(), so there is no line-break trap to worry about.

This is the same priming-read pattern as the adder, with a word as the sentinel and an if-else chain in the middle. dance is not a command, so it lands in the final else. The program compares strings with cmd.equals("quit"), never with ==, because == asks whether two variables point at the very same object while equals compares the text. That distinction was the heart of references and equality.

Two other ways to read a line#

Java 25 added a small class called IO with methods for the console. IO.readln(prompt) prints the prompt, then reads one whole line and returns it as a String. IO lives in java.lang, so it needs no import.

IO.readln always gives you text, so the age goes through Integer.parseInt. There is no trap here, because every call reads exactly one whole line. Read the keyboard with either IO.readln or a Scanner in one program, not both: the documentation warns that after the first readln call, any other use of System.in gives unspecified results.

You will also see older code read the keyboard with a BufferedReader wrapped around System.in. Its readLine() method returns one whole line, much like IO.readln. BufferedReader comes up properly in the next lesson, where it reads files.

Further reading#

• Scanner in the Java SE 25 API documentation, with every next and hasNext method and the exceptions each one throws
• The IO class in the Java SE 25 API documentation, including readln
• JEP 512: Compact Source Files and Instance Main Methods, the Java 25 change that added the IO class