Java Basics

public record Location(double latitude, double longitude) {
    public Location {
        if (Math.abs(latitude) > 90 || Math.abs(longitude) > 180) {
            throw new IllegalArgumentException("Value out of range");
        }
    }

    public boolean inNorthernHemisphere() {
        return latitude > 0;
    }
}

Records Behind the Scenes

Records are just classes. You should use them as often as possible, because immutability is awesome. But, to be a good Java programmer, you should know what goes on behind the scenes. Records give you immutability for free, method accessors for free, and a proper value-based equality method. Doing all those things yourself is surprisingly really hard! Value-based equality is super hard, because:

• There are a ton of restrictions placed on how the equals method is supposed to behave, seemingly the least of which is the fact that Java requires that the thing you compare to can belong to any class.
• For very technical reasons outside the scope of this tutorial, you should NEVER override equals without overriding hashCode.

Yikes. The details are just too technical at this point. So we’ll just present some code and study it in class:

// Don't write this yourself, we're only showing what the record produces.

import java.util.Objects;

public class Point {
    public static final Point ORIGIN = new Point(0, 0);

    private final double x;
    private final double y;

    public Point(double x, double y) {
        if (Double.isNaN(x) || Double.isNaN(y)) {
            throw new IllegalArgumentException("Coordinates can not be NaN");
        }
        this.x = x;
        this.y = y;
    }

    public double x() {
        return x;
    }

    public double y() {
        return y;
    }

    public double distanceFromOrigin() {
        return Math.hypot(x, y);
    }

    public Point reflectionAboutOrigin() {
        return new Point(-x, -y);
    }

    public static Point midpointOf(Point p, Point q) {
        return new Point((p.x + q.x) / 2.0, (p.y + q.y) / 2.0);
    }

    @Override
    public boolean equals(Object o) {
        return (o instanceof Point other) && x == other.x && y == other.y;
    }

    @Override
    public int hashCode() {
        return Objects.hash(x, y);
    }

    @Override
    public String toString() {
        return "Point[x=" + x + ", y=" + y + "]";
    }
}

Yay, new Java features were introduced here! We’ll go over the example in class in some detail, but first, let’s use the class to get a sense of things. Put the file Point.java in the same folder in which you launched jshell. Then follow along:

jshell> /open Point.java

jshell> var p = new Point(3, 8)
(3.0, 8.0)

jshell> p.distanceFromOrigin()
8.54400374531753

jshell> Point.midpointOf(new Point(1,1), new Point(3,3))
(2.0, 2.0)

jshell> var q = new Point(3, 8)
(3.0, 8.0)

jshell> Map.of(new Point(1, 1), "dog", new Point(1, 1), "rat")
|  Exception java.lang.IllegalArgumentException: duplicate key: (1.0, 1.0)

Now let’s break down the code and learn some new things:

• The class has three fields, but one of them is marked static. Non-static fields belong to the instances and are called instance fields; static fields belong to the class and are called class fields. Instances created with new Point have their own x and y fields; the static field ORIGIN belongs to the class and is accessed like this: Point.ORIGIN.
• The midpointOf method is marked static, so it is called as Point.midpointOf(p, q); that is, it is called on the class, not on any instance. It is called a class method. The other methods are all instance methods.
• We are following Java convention and making all of our instance fields private. (The rectangle class we saw earlier is a bit of an anomaly.) Details about access modifiers and more are in a separate page of notes. You can also read about them in the Java Language Specification.
• Because the equals, hashCode, and toString methods already have default implementations for all classes, we mark them with the @Override annotation when defining our customized behaviors.
• The equals method is designed to be used as p.equals(q) where q is any object whatsoever, and not necessarily another Point object. This means to implement properly, you must check that this other object is a Point. The instanceof operator will perform this test and if it passes, give you a new properly type-constrained Point variable for you to begin checking the equality of each corresponding field.
• For technical reasons, whenever you override equals you have to override hasCode. Fortunately this is easy: pass the fields you care about to Objects.hash and you are good to go.
• In case you are dying of curiosity about this hashCode thing, we’ll just say this for now: if you don’t override hashCode then points won’t work as dictionary keys or set members the way you expect.

You don’t HAVE to override equals and hashCode

It’s likely that for most classes you will ever write, you won’t ever have to compare them at all. But you DO need to know that if you do, == will check identity only, so in those cases where to want field-based equality, you have to walk the walk and override both.

There is so much more to classes.

As this is only an introductory tutorial, we barely scratched the surface of classes, but that’s enough for now. If interested, see this page of notes discussing Java classes in much more detail.

Understanding null

The value null (a.k.a. the null reference) is a member of every reference type. It’s annoying, dangerous, and error-prone. It’s inventor, Tony Hoare, calls it his Billion-Dollar Mistake because of the havoc it has wrought over the years. But it is an inescapable fact of life in Java. You cannot avoid it. So you have to understand it. The first thing to understand is: null does not have any fields or methods. Any attempt to dereference null throws a NullPointerException.

jshell> var message = "Stay behind the yellow line"
"Stay behind the yellow line"

jshell> message.toUpperCase()
"STAY BEHIND THE YELLOW LINE"

jshell> message = null
null

jshell> message.toUpperCase()
|  Exception java.lang.NullPointerException

So what does this mean? It means whenever you use a dot, as in the expression r.x (where r is a reference and x is a field or method), ask yourself “Is there any way r can be null here?” Try to make sure your code never will! If you can’t avoid it, you need to probably make a check:

if (r != null) {
    doSomethingWith(r.x)
}

Why do we have null?

It’s supposed to stand for “no value here.” For example:

    var supervisor = new Supervisor("Tina", ...);

means you have a supervisor named Tina, whereas

    var supervisor = null;

means you don’t have a supervisor. The problem is that the expression (for example):

    supervisor.performPerformanceReview(employee)

can throw a NullPointerException. You can get around all this by using the class Optional. We’re not going to cover it in these notes. It’s a huge improvement, but you have to go through a learning curve and you have to use it properly. It doesn’t solve all your problems, but it’s good to know about, at least.

Now you know what public static void main is

In Java, all your code has to be in some class! So if you just want to write a simple command line application, you need a class. But you don't want to create an object just to run your code, so...we use a static method! The method needs to be public so it can be seen from outside the class, and is marked void because it does not return anything. The command line arguments are all rolled into an array, so there you go:

public class Greeter {
    public static void main(String[] args) {
        System.out.print("Hello there");
        if (args.length > 0) {
            System.out.print(", " + args[0]);
        }
        System.out.println(".");
    }
}

Classes in the standard library

Your Java implementation comes with thousands upon thousands of built-in classes. Classes are grouped into packages, so every class has a fully qualified name such as java.time.LocalDate, java.awt.Rectangle, or javax.crypto.KeyGenerator.

If you don’t want to use the full class name, you can import the class at the top of your program, or in JShell. (One exception: you don’t have to qualify classes from java.lang.)

public class NewYearCountdown {
    public static void main(String[] args) {
        var today = java.time.LocalDate.now();
        var nextNewYearsDay = java.time.LocalDate.of(today.getYear() + 1, 1, 1);
        var days = java.time.temporal.ChronoUnit.DAYS.between(today, nextNewYearsDay);
        System.out.println("Hello, today is " + today);
        System.out.printf("There are %d days until New Year’s Day%n", days);
    }
}

$ javac NewYearCountdown.java && java NewYearCountdown
Hello, today is 2020-01-09
There are 358 days until New Year’s Day

Fun tip

JShell actually imports hundreds of frequently used classes to be nice to you, but far from all of them, so be ready to do a lot of importing when needed.

Enums

An enum is a simple kind of class, one whose instances are fixed once and for all. You can never create another instance of the type. Examples:

jshell> enum TrafficLightColor { RED, AMBER, GREEN }
|  created enum TrafficLightColor

jshell> enum Direction { NORTH, EAST, SOUTH, WEST }
|  created enum Direction

jshell> var stopColor = TrafficLightColor.RED
RED

jshell> stopColor
RED

jshell> System.out.println(stopColor)
RED

jshell> TrafficLightColor.valueOf("GREEN")
GREEN

Like classes, the values of an enum type can have properties and behaviors attached to them. Perhaps the best way to see how this works is to study this modification of the Enum example from the Oracle’s Java™ Tutorials:

public enum Planet {
    MERCURY (3.303e+23, 2.4397e6),
    VENUS   (4.869e+24, 6.0518e6),
    EARTH   (5.976e+24, 6.37814e6),
    MARS    (6.421e+23, 3.3972e6),
    JUPITER (1.9e+27,   7.1492e7),
    SATURN  (5.688e+26, 6.0268e7),
    URANUS  (8.686e+25, 2.5559e7),
    NEPTUNE (1.024e+26, 2.4746e7);

    public final double mass;   // in kilograms
    public final double radius; // in meters

    Planet(double mass, double radius) {
        this.mass = mass;
        this.radius = radius;
    }

    double surfaceGravity() {
        // G is the universal gravitational constant (m³ / kg / s²)
        double G = 6.67300E-11;
        return G * mass / (radius * radius);
    }

    double surfaceWeight(double otherMass) {
        return otherMass * surfaceGravity();
    }

    public static void main(String[] args) {
        for (var p: Planet.values()) {
            System.out.printf("Radius of %s ≈ %.0f m%n", p, p.radius);
            System.out.printf("Mass of %s ≈ %.3e kg%n", p, p.mass);
            System.out.printf("Surface gravity of %s ≈ %f m/s²%n", p, p.surfaceGravity());
            System.out.printf("100kg on %s weighs %g kg•m/s²%n", p, p.surfaceWeight(100.0));
            System.out.println();
        }
    }
}

The public static void main is only there to illustrate how enums are used. How convenient:

$ javac Planet.java && java Planet
Radius of MERCURY ≈ 2439700 m
Mass of MERCURY ≈ 3.303e+23 kg
Surface gravity of MERCURY ≈ 3.703027 m/s²
100kg on MERCURY weighs 370.303 kg•m/s²

Radius of VENUS ≈ 6051800 m
Mass of VENUS ≈ 4.869e+24 kg
Surface gravity of VENUS ≈ 8.871392 m/s²
100kg on VENUS weighs 887.139 kg•m/s²

.
.
.
Radius of NEPTUNE ≈ 24746000 m
Mass of NEPTUNE ≈ 1.024e+26 kg
Surface gravity of NEPTUNE ≈ 11.158635 m/s²
100kg on NEPTUNE weighs 1115.86 kg•m/s²

Let’s unpack a bit:

• enum Planet declares a new enum type called Planet
• There are exactly eight instances of the type, MERCURY through NEPTUNE.
• Each of the instances have two fields (mass and radius), used, for example, as follows: MARS.mass and SATURN.radius.
• Each of the instances have two methods (surfaceGravity and surfaceWeight), used, for example, as follows: EARTH.surfaceGravity() and VENUS.surfaceWeight(7.95).
• Enums have constructors, just as classes do.
• We threw in a main for simplicity; real classes hardly ever have one. Our main method does illustrate one cool thing about enums: the static values method returns an array of the instances of the type. Nice for iteration!

Interfaces

When multiple classes have overlapping sets of methods, but implement them in a slightly different way, interfaces can be incredibly useful. Just a quick example for now: a two-dimensional shape is something for which you can compute an area and a perimeter. It makes sense, then, to talk about lists of shapes and operate on those lists, often without worrying about the specific type of shape.

interface Shape2d {
    double perimeter();
    double area();
}

record Circle(double radius) implements Shape2d {
    public double perimeter() { return 2 * Math.PI * radius(); }
    public double area() { return Math.PI * radius() * radius(); }
}

record Rectangle(double width, double height) implements Shape2d {
    public double perimeter() { return 2 * (height() + width()); }
    public double area() { return width() * height(); }
}

Here’s an operation that operates on entities “through their interfaces”:

var sum = 0.0;
for (var shape: List.of(new Circle(3), new Rectangle(2.2, 8.88), new Circle(5.13))) {
    sum += shape.area();
}

Note that you can have variables, fields, and parameters of an interface type:

class Player {
    String name;
    Shape2d favoriteShape;
}

Shape s1 = new Circle(1.0);
Shape s2 = new Rectangle(2.0, 2.0);

double halfwayAround(Shape2d s) { return s.perimeter() / 2.0; }

While an interface is indeed a type, it is not something you can instantiate:

jshell> var s = new Shape2d()
|  Error:
|  Shape2d is abstract; cannot be instantiated
|  var s = new Shape2d();

Statements

Expressions are evaluated to produce results. Statements are executed to perform actions. In Java, statements always appear inside the body of a method.

Simple Statements

Here is an example program that illustrates five kinds of simple statements inside the main method of a small application (by “simple” we mean statements that aren’t made up of other statements):

public class SimpleStatementDemo {
    public static void main(String[] args) {
        var happiness = 7;               // Local variable declaration
        happiness = happiness + 2;       // Assignment statement
        happiness++;                     // IncrementOrDecrement statement
        ;                                // Empty statement
        System.out.println(happiness);   // Method invocation
    }
}

Note the difference between a variable declaration and an assignment. The former brings a variable into existence; the latter updates the value of an already-existing variable.

Conditionals

The If Statement

The if statement selects a computation by examining a sequence of conditions until it finds one that is true:

if (prohibitedFromVoting) {
    System.out.println("Sorry, you can't vote");
} else if (age >= 19) {
    System.out.println("I hope you are a regular voter");
} else if (age >= 18) {
    System.out.println("Congratulations, new voter");
} else {
    var yearsToWait = 18 - age;
    System.out.printf("You can vote in " + yearsToWait + " years");
}

The Switch Statement

A switch statement can be used when all the choices are based on the value of a single expression (which must be a char, byte, short, int, Character, Byte, Short, Integer, String, or of an enum type):

switch (direction) {
    case "North" -> row--;
    case "East" -> column++;
    case "West" -> column--;
    case "South" -> row++;
    default -> throw new IllegalArgumentException(
            "You should have used an enum!");
}

Avoid the legacy switch

Java supports the ugly version of the switch that C, C++, and JavaScript have. This version uses a : instead of -> and each switch block (the part after the case) is a sequence of statements, which “fall through” to the next case unless a break is present. There is no reason to mess with this version at all. It was created in the ancient period of programming languages where folks were looking for expressive ways to take advantage of the hardware of the day.

Alternatives to If and Switch Statements

Be careful not to overuse if and switch statements. Quite frequently the expression forms of each are more appropriate than the statement forms. So replace this kind of if statement:

// THIS CODE IS POOR: IT EMPHASIZES THE "IF"
String hemisphere;
if (latitude >= 0) {
    hemisphere = "north";
} else {
    hemisphere = "south";
}

with the conditional expression:

// THIS CODE IS PROPER: IT EMPHASIZES THE ASSIGNMENT
var hemisphere = latitude >= 0 ? "north" : "south";

Switches can be used as expressions, too:

var word = switch (amount) {
    case 1 -> "single";
    case 2 -> "pair";
    case 3 -> "trio";
    case 12 -> "dozen";
    case 4, 5, 6 -> "few";
    default -> String.valueOf(amount);
};

And never use if statements for simple “lookups”!

var state = "NSW"; // (for example)

// THIS CODE IS VERY BAD, THERE IS TOO MUCH REPETITION
String capital;
if (state == "SA") {
    capital = "Adelaide";
} else if (state == "QLD") {
    capital = "Brisbane";
} else if (state == "ACT") {
    capital = "Canberra";
} else if (state == "NT") {
    capital = "Darwin";
} else if (state == "TAS") {
    capital = "Hobart";
} else if (state == "VIC") {
    capital = "Melbourne";
} else if (state == "WA") {
    capital = "Perth";
} else if (state == "NSW") {
    capital = "Sydney";
} else {
    throw new IllegalArgumentException("No such state or territory");
}
System.out.println(capital);

You should use maps. This is what maps are for. You should focus on the the data:

// THIS CODE IS BEAUTIFUL
var capitals = Map.of(
    "SA", "Adelaide",
    "QLD", "Brisbane",
    "ACT", "Canberra",
    "NT", "Darwin",
    "TAS", "Hobart",
    "VIC", "Melbourne",
    "WA", "Perth",
    "NSW", "Sydney"
);
System.out.println(capitals.get(state));

Perhaps you cooooooooouuuuullllllddddd use a switch expression for this:

// THIS CODE IS OK BUT THE MAP IS PROBABLY BETTER
var capital = switch (state) {
    case "SA" -> "Adelaide";
    case "QLD" -> "Brisbane";
    case "ACT" -> "Canberra";
    case "NT" -> "Darwin";
    case "TAS" -> "Hobart";
    case "VIC" -> "Melbourne";
    case "WA" -> "Perth";
    case "NSW" -> "Sydney";
    default -> throw new NoSuchElementException();
};

You can also take advantage of the short-circuit behavior of && and || for conditional computation. Suppose you were programming a robot and you created the methods swim, run, bike, goThroughDoor, and goThroughWindow, each of which did its thing and returned a boolean value saying whether the task succeeded or not. Now you can write some nice clean expressions:

// The robot won’t bike unless the swim succeeded, and won’t run unless the bike succeeded
var finishedTriathlon = swim() && bike() && run();

// The robot will only try the window if going through the door failed
var gotIn = goThroughDoor() || goThroughWindow();

Iteration

Java has a few statements for doing something repeatedly.

The For-Statement (Definite Iteration)

It you know exactly what you be iterating through (e.g., a range of numbers, the elements of a list, the characters of string), use the famous for loop. Examples only:

jshell> for (var x: List.of(3, 2, 1)) {
   ...>     System.out.println("Count is " + x);
   ...> }
Count is 3
Count is 2
Count is 1

jshell> for (var c: "Hello".toCharArray()) {
   ...>     System.out.println(Character.toUpperCase(c));
   ...> }
H
E
L
L
O

There is a powerful form of the for-statement that is normally used to numeric ranges:

    for ( before ; shouldIKeepGoing ; atEndOfEachIteration)

The before part is done once, then as long as the middle part is true, the body is executed and the last part happens (which sets you up for the next iteration). As a trivial example, here’s counting by 5s:

for (var i = 5; i <= 100; i += 5) {
    System.out.println(i);
}

It’s not uncommon to see nested for loops. Here is a multiplication table application. It introduces some new features, so run the application yourself and be ready to discuss it with friends in class.

class MultiplicationTableApp {

    private static final int MIN_SIZE = 1;
    private static final int MAX_SIZE = 20;

    private static final String ARGUMENT_COUNT_ERROR = "Exactly one command line argument required";
    private static final String ARGUMENT_FORMAT_ERROR = "Argument must be an integer";
    private static final String SIZE_ERROR = String.format(
            "Size must be between %d and %d", MIN_SIZE, MAX_SIZE);

    private static void printTable(int size) {
        if (size < MIN_SIZE || size > MAX_SIZE) {
            throw new IllegalArgumentException(SIZE_ERROR);
        }
        for (var i = 1; i <= size; i++) {
            for (var j = 1; j <= size; j++) {
                System.out.printf("%4d", i * j);
            }
            System.out.println();
        }
    }

    public static void main(String[] args) {
        try {
            if (args.length != 1) {
                throw new IllegalArgumentException(ARGUMENT_COUNT_ERROR);
            }
            printTable(Integer.parseInt(args[0]));
        } catch (NumberFormatException e) {
            System.err.println(ARGUMENT_FORMAT_ERROR);
        } catch (IllegalArgumentException e) {
            System.err.println(e.getLocalizedMessage());
        }
    }
}

The While-Statement (Indefinite Iteration)

When you don’t have a definite collection of things to iterate through, and you just need to keep going as long as some condition holds, use the while statement. Here’s an example. A player starts at level 5 and needs to get to level 90. At each “turn” the player moves a randomly-generated number of levels, between -3 and 7. If the player reaches (or goes below) zero, they lose. If they reach (or exceed) level 90, they win. Here’s a complete, runnable program. (Super bonus fun time: it introduces random numbers!)

import java.util.Random;

public class NonInteractiveLevelGame {

    private static int MIN_LEVEL = 0;
    private static int MAX_LEVEL = 90;

    public static void main(String[] args) {
        var random = new Random();
        var level = 5;
        System.out.println("Beginning on level " + level);

        while (level > MIN_LEVEL && level < MAX_LEVEL) {
            var steps = random.nextInt(11) - 3;
            level += steps;
            System.out.println("Took " + steps + " steps, now on level " + level);
        }
        if (level <= MIN_LEVEL) {
            System.out.println("Sorry you lost");
        } else {
            System.out.println("Congratulations!");
        }
    }
}

Alternatives to the for and while statements

As you gain experience as a programmer, you will learn to use software libraries that contain plenty of operations that hide a lot of looping operations so you don’t have to write loops yourself. For example, in Java, there are built-in operations to:

• Apply an operation to every element in a collection
• Find the first (or last) element in a collection that satisfies a property
• Keep all the elements in a collection that satisfy a property and discard the rest
• Find the minimum, maximum, sum, average, or median of all the elements in a collection
• ...and many more

But don’t worry if you don’t know this yet

Mastering programming is a journey. No one begins their career as an expert. It’s okay to write your own loops to do routine tasks while you are learning!

Disruption

Statements are normally executed one after the other, but there are four ways to disrupt the flow. In practice they are almost always embedded in an if statement (do you see why?):

A return statement immediately exits the current method. If the method is not marked void, it will return something.

boolean isPrime(int n) {
    if (n < 2) {
        return false;
    } else if (n == 2 || n == 3) {
        return true;
    } else if (n % 2 == 0 || n % 3 == 0) {
        return false;
    }
    for (int k = 5, w = 2; k * k <= n; k += w, w = 6 - w) {
        if (n % k == 0) {
            return false;
        }
    }
    return true;
}

A break statement immediately exits an entire loop statement, abandoning the current and all future iterations. A continue statement immediately abandons the current iteration (only) and continues with the next iteration.

import java.util.Random;

public class GuessingGame {
    public static void main(String[] args) {
        var secret = new Random().nextInt(100) + 1;
        var message = "Welcome";

        while (true) {
            var input = System.console().readLine(message + ". Guess a number: ");
            int guess;

            try {
                guess = Integer.parseInt(input);
            } catch (NumberFormatException e) {
                message = "Not an integer";
                continue;
            }

            if (guess < secret) {
                message = "Too low";
            } else if (guess > secret) {
                message = "Too high";
            } else {
                System.out.println("YOU WIN!");
                break;
            }
        }
    }
}

$ javac GuessingGame.java && java GuessingGame
Welcome. Guess a number: fifty
Not an integer. Guess a number: 50
Too low. Guess a number: 75
Too low. Guess a number: 89
Too high. Guess a number: 83
Too high. Guess a number: 80
Too low. Guess a number: 82
YOU WIN!

A throw statement abandons the rest of its block, throwing an exception. We’ve seen this statement used a few times above! (Go back and take a look.) We’ll see more about exceptions later.

Summary of Java statements

Here is a complete list of Java statements. We’ve discussed most of them already, but don’t have the space in this introductory tutorial for all of them. Still, this table should be useful to review the ones we’ve seen and get a sneak peek into the others. (If interested you may wish to read about all the statements in the official Java Language Specification.)

Arrays

An array is a fixed-size, mutatble, ordered sequence of values. Internally, the elements are packed together tightly in memory making it blindingly fast to access by position. The index of the first element of the array is 0. The length of the array is the number of elements.

  0   1   2   3   4   5   6    7    8
┌───┬───┬───┬───┬───┬───┬───┬────┬────┐
│ 0 │ 1 | 1 | 2 | 3 | 5 | 8 | 13 | 21 |
└───┴───┴───┴───┴───┴───┴───┴────┴────┘

Arrays in Java can never grow or shrink! They can, however, have individual elements updated (they are mutable). Array expressions are normally tagged with the type of their elements:

jshell> var foods = new String[]{"kefir", "zhoug", "orange juice", "lemons"}
String[4]{"kefir", "zhoug", "orange juice", "lemons"}

jshell> foods.length
4

jshell> foods[0]
"kefir"

jshell> foods[3]
"lemons"

jshell> foods[4]
|  Exception java.lang.ArrayIndexOutOfBoundsException

jshell> foods[-1]
|  Exception java.lang.ArrayIndexOutOfBoundsException

jshell> foods[2] = "barazek"

jshell> foods
String[4] { "kefir", "zhoug", "barazek", "lemons" }

There’s one exception to the rule of having to tag arrays with their element type: if you declare an array variable with the type (instead of using var) you can leave off the tag in the initializer:

jshell> int[] picks = {5, 50, 2, 8, 13, 21}

Simple array operations

Let’s get started with copying and filling and printing. In Java, arrays are objects, so = will only copy pointers, not array elements; use copyOf to copy the elements. For printing, use Arrays.toString for arrays of primitives, and Arrays.deepToString for arrays of objects:

jshell> import java.util.Arrays

jshell> var frens = new String[]{"Ratty", "Mole", "Badger", "Toad", "Otter", "Pan"}
String[6]{"Ratty", "Mole", "Badger", "Toad", "Otter", "Pan"}

jshell> Arrays.copyOf(frens, frens.length)
String[6] { "Ratty", "Mole", "Badger", "Toad", "Otter", "Pan" }

jshell> Arrays.copyOfRange(frens, 2, 5)
String[3] { "Badger", "Toad", "Otter" }

jshell> var ones = new int[10]; Arrays.fill(ones, 1)

jshell> ones
int[10] { 1, 1, 1, 1, 1, 1, 1, 1, 1, 1 }

jshell> System.out.println(ones)
[I@45283ce2

jshell> System.out.println(Arrays.toString(ones))
[1, 1, 1, 1, 1, 1, 1, 1, 1, 1]

jshell> System.out.println(frens)
[Ljava.lang.String;@4629104a

jshell> System.out.println(Arrays.toString(frens))
[Ratty, Mole, Badger, Toad, Otter, Pan]

jshell> int[][] matrix = {{10, 20, 30}, {5, 1, 8}}

jshell> System.out.println(matrix)
[[I@6d21714c

jshell> System.out.println(Arrays.toString(matrix))
[[I@4ccabbaa, [I@4bf558aa]

jshell> System.out.println(Arrays.deepToString(matrix))
[[10, 20, 30], [5, 1, 8]]

Array equality—be careful!

Since arrays are objects, the == operator on arrays will only compare identities, not array elements. Use Arrays.equals for arrays of primitives, and Arrays.deepEquals for arrays of objects:

jshell> var a = new int[]{10, 300, 99, -987}

jshell> var b = new int[]{10, 300, 99, -987}

jshell> a == b
false

jshell> Arrays.equals(a, b)
true

jshell> int[][] matrix1 = {{5, 13}, {8, 2}}

jshell> int[][] matrix2 = {{5, 13}, {8, 2}}

jshell> Arrays.equals(matrix1, matrix2)
false

jshell> Arrays.deepEquals(matrix1, matrix2)
true

Wait why not a.equals(b)?

I dont know. That doesn’t work for arrays. Use Arrays.equals(a, b) or Arrays.deepEquals(a, b) instead. I guess arrays are special.

Splitting and joining

You can split a string into a string array, and join the elements of a string array into a big string.

jshell> var userRecord = "255:jdoe:Jane Doe:admin:g727gfrwyVDTQRugP12CFvbsjdv29m"

jshell> userRecord.split(":")
String[5] { "255", "jdoe", "Jane Doe", "admin", "g727gfrwyVDTQRugP12CFvbsjdv29m" }

jshell> var path = new String[]{"up", "right", "right", "down", "left"}

jshell> String.join("->", path)
"up->right->right->down->left"

Sorting

If you just need to sort an array of numbers, the plain old Arrays.sort is fine:

jshell> var picks = new int[]{34, 8, 21, 5, 1, 2}
int[6] { 34, 8, 21, 5, 1, 2 }

jshell> Arrays.sort(picks)

jshell> picks
int[6] { 1, 2, 5, 8, 21, 34 }

Array sortiing is destructive

it sorts “in place” rather than returning a new sorted array.

Why do we sort? Sorting is useful for people reading reports. After sorting, it’s easier to remove duplicates. And perhaps most importantly, sorting makes it easier to find things. If your array is sorted, you can use Arrays.binarySearch, which will tell you, very efficiently, whether a particular value is in your array, and if so where, and if not, where would it go.

Summing an array of numbers

Beyond splitting, joining, searching, and sorting, most operations on arrays require you first turn them into a stream. There are historical reasons for this weirdness we can get into later; but for now, let’s just look at the simplest example: summing a numeric array.

jshell> var scores = new int[]{80, 20, 19, -28, 12}
int[5] { 80, 20, 19, -28, 12 }

jshell> Arrays.stream(scores).sum()
103

jshell> Arrays.stream(new int[]{80, 20, 19, -28, 12}).sum()
103

jshell> Arrays.stream(new int[]{}).sum()
0

Mapping and Filtering

Mapping an array is applying an operation to each element in the array, producing an array of the results. Filtering is when you make a new array by just keeping certain elements of the original array. Again, this only works on streams, so we make a stream, do the operations, and pull the stream elements out as a new array:

jshell> var words = "Because I could not stop for Death".split(" ")
String[7] { "Because", "I", "could", "not", "stop", "for", "Death" }

jshell> Arrays.stream(words).filter(
   ...>   s -> s.length() > 3).map(
   ...>   s -> s.toLowerCase()).toArray()
Object[4] { "because", "could", "stop", "death" }

What is the deal with these streams?

Are you wondering why you can’t just map, filter, sum, min, max, average, etc. directly on arrays? Why the streams?

Believe it or not, streams are a good thing! Arrays are not the only kind of sequence! There are also lists, files in a folder, lines of text from a file, sequences of values from ranges, etc. etc. Java has ways to make streams from each of these things. And since all the fancy operations are defined on streams, voilá: they now apply to all these data sources, provided there’s a way to make a stream from them.

And there’s more: the Java Virtual Machine (the process than runs Java programs) can actually figure out internally the best ways to optimize stream operations. Also, wiring together stream pipelines is pretty fun, once you get the hang of it.

Oh, and stream operations are what data scientists do a lot, and data scientists are highly paid. 💰

Varargs

Arrays are by design extremely primitive, with a rather ugly syntax and some design flaws (such as covariance and the need for run-time type checking which you will learn about some day in a programming languages course). There is one very cool Java feature, though, that mitigates some of the syntactic ugliness (yay!): if the last parameter to a method is an array, you can arrange to just call the function with the arguments unpacked:

double average(double... a) {
    // Inside the method, a is an array of doubles
    if (a.length == 0) {
        return Double.NaN;
    }
    var sum = 0.0;
    for (var x: a) {
        sum += x;
    }
    return sum / a.length;
}

// When called, the arguments will be packed into an array
average(2, 92.05, -29, 11.7, 22.3)   // 19.81
average()                            // NaN
average(99)                          // 99.0
average(5, 13)                       // 9.0

This language feature is called varargs since we’ve essentially made an operation that takes “a variable number of arguments.”

Why are varargs cool? The alternative would be to declare the function as double average(double[] a) and call it with average(new double[]{5, 10, 20, -15} (with the ugly type prefix).

Lists

Java has another kind of sequence, called the list. How do lists differ from arrays?

Here are a couple ways to create lists. Note the List.of syntax gives you a fixed-size list, but the new ArrayList form allows for growth:

jshell> var frens = List.of("Kim", "Ron", "Wade")
[Kim, Ron, Wade]

jshell> frens.add("Bonnie")
|  Exception java.lang.UnsupportedOperationException

jshell> var frens = new ArrayList<String>(List.of("Kim", "Ron", "Wade"))
[Kim, Ron, Wade]

jshell> frens.add("Monique")
true

jshell> frens
[Kim, Ron, Wade, Monique]

There are quite a few ways to make lists; Java is so flexible. For reference, here are a few examples:

Operations on all lists

Here are some of the methods that apply to all lists, whether resizable or not, whether immutable or not, shown by example:

var a = List.of(100, 200, 200, 500, 300, 200, 100);

a.isEmpty()                       // false
a.size()                          // 7
a.get(3)                          // 500
a.contains(300)                   // true
a.containsAll(List.of(200, 100))  // true
a.indexOf(200)                    // 1
a.lastIndexOf(200)                // 5
a.subList(2, 4)                   // [200, 500]
a.equals(List.of(100, 200, 500))  // false

You can also operate on arbitrary lists with these static methods from the Collections class:

var a = List.of(100, 200, 200, 500, 300, 200, 100);
var b = List.of(100, 200, 300, 400, 700);

Collections.disjoint(a, b)        // false
Collections.max(a)                // 500
Collections.min(a)                // 100
Collections.frequency(a, 200)     // 3
Collections.frequency(a, 500)     // 1
Collections.binarySearch(b, 400)  // 3
Collections.binarySearch(b, 100)  // 0
Collections.binarySearch(b, 500)  // -5

Operations on mutable lists

The three list methods (set, replaceAll, and sort) work on any list that allow individual elements to be changed. They don’t change the size of the list:

jshell> var a = Arrays.asList(34, 5, 2, 8)
[34, 5, 2, 8]

jshell> a.set(1, 89)
5

jshell> a
[34, 89, 2, 8]

jshell> a.replaceAll(x -> x + 10)

jshell> a
[44, 99, 12, 18]

jshell> a.sort(Comparator.naturalOrder())

jshell> a
[12, 18, 44, 99]

jshell> a.sort(Comparator.reverseOrder())

jshell> a
[99, 44, 18, 12]

You can also operate on mutable lists with these static methods from the Collections class:

jshell> var a = Arrays.asList(100, 90, 80, 70, 60, 50, 40, 30, 20, 10)
[100, 90, 80, 70, 60, 50, 40, 30, 20, 10]

jshell> Collections.shuffle(a) ; a
[10, 30, 70, 100, 40, 20, 90, 50, 60, 80]

jshell> Collections.reverse(a) ; a
[80, 60, 50, 90, 20, 40, 100, 70, 30, 10]

jshell> Collections.sort(a) ; a
[10, 20, 30, 40, 50, 60, 70, 80, 90, 100]

jshell> Collections.rotate(a, 3) ; a
[80, 90, 100, 10, 20, 30, 40, 50, 60, 70]

jshell> Collections.swap(a, 2, 7) ; a
[80, 90, 50, 10, 20, 30, 40, 100, 60, 70]

jshell> Collections.fill(a, 3) ; a
[3, 3, 3, 3, 3, 3, 3, 3, 3, 3]

Operations on variable-sized lists

Here are some operations that actually grow or shrink a list object:

Let’s try a couple:

jshell> var a = new ArrayList<String>(List.of("Once", "I", "read", "a", "novel"))
[Once, I, read, a, novel]

jshell> a.removeIf(w -> w.length() < 3)
true

jshell> a
[Once, read, novel]

In JShell, practice with each of the above operations until you know them well.

ArrayLists vs. LinkedLists

You’ve noticed Java comes with both ArrayLists and LinkedLists. Why two kinds of lists? It turns out they have different performance characteristics. Roughly, ArrayLists are better when you do a lot of looking up values by position, and LinkedLists are better when you do a lot of inserting and deleting. Each type has some extra methods that are not common to all lists. Details can easily be found elsewhere.

The type of list elements

Okay here’s a real facepalm: Lists are not allowed to hold primitive values!

jshell> var a = new ArrayList<int>()
|  Error:
|  unexpected type
|    required: reference
|    found:    int

jshell> var a = new ArrayList<Integer>()
a ==> []

So you cannot make lists that hold boolean, byte, char, short, int, long, float, or double. But you know what? Java has built-in classes called Boolean, Byte, Character, Short, Integer, Long, Float, and Double. For the most part, instances of these classes interoperate with the values of the primitive types. It’s a little annoying, but you will be able to get used to it. Linguistically speaking the object types are called wrapper classes, and when Java automatically generates a wrapper for a primitive, it is called auto-boxing, and when Java automatically gets the primitive out of a wrapper, it is called auto-unboxing. Not all boxing and unboxing can happen automatically, though.

The type List

Because ArrayLists and LinkedLists are different kinds of lists, you’ve probably already guessed that Java has a interface type for all lists, and indeed it does. List is an interface type, and the classes ArrayList and LinkedList just happen to implement this interface, so they have all the methods specified by List.

We can take advantage of this and write operations that operate on any kind of list! Here’s a small example. We have a method can accepts any kind of Integer list (Array, Linked, or whatever List.of produces) and it returns the product of its elements:

jshell> int productOf(List<Integer> a) {
   ...>     return a.stream().reduce(1, (x, y) -> x * y);
   ...> }
|  created method productOf(List<Integer>)

jshell> productOf(List.of(3, 8, -2))
-48

jshell> var b = new ArrayList<Integer>(List.of(3, 2, 10))
[3, 2, 10]

jshell> productOf(b)
60

jshell> var b = new LinkedList<Integer>(Collections.nCopies(5, 2))
[2, 2, 2, 2, 2]

jshell> productOf(b)
32

There is so much more to interfaces, all way beyond the scope of these notes. But hopefully you appreciate the separation here between behaviors (interfaces) and the fact that different implementations of interfaces can exist.

What about methods that work on lists of elements of any type?

Oh dear, well yes, such things are possible, but there are so many aspects to this simple-sounding question, leading to wildcards, bounded wild cards, covariance vs. contravariance vs. invariance, just for starters. The page you are reading covers only the basics of Java, so you’ll have to look elsewhere for all that good stuff.

Lists and streams

If you want to use some of the cool stream operations (map, filter, flatMap, takeWhile, distinct, count, reduce, collect, min, max, findFirst, findAny, etc.) you just need to make a stream from your list.

Fortunately, it’s pretty easy: for any list a (doesn’t matter what kind of list!), you just need to write a.stream():

jshell> var a = List.of(8, 2, 9, 1, 10)

jshell> a.stream().takeWhile(x -> x % 2 == 0).count()
2

Maps (Dictionaries)

You’re probably familiar with the way a dictionary maps words to their definitions. That’s why Java calls dictionaries maps. What else can we map? How about:

• Phrases in one language to their translations in another
• Geographic regions to their capital
• Words to the number of times they appear in a document
• Words to the (list of) locations in which they appear in a document
• Server names to IP addresses
• Error codes to descriptions
• Zip codes to the latitude and longitude of their post office

Here is a mapping of the regions of Eswatini to their capitals:

var eswatiniCapitals = Map.of(
    "Hhohho", "Mbabane",
    "Manzini", "Manzini",
    "Lubombo", "Siteki",
    "Shiselweni", "Nhlangano"
)

Maps map keys to values. The keys of the above map are {"Hhohho", "Manzini", "Lubombo", "Shiselweni"}. The values are {"Mbabane", "Manzini", "Siteki", "Nhlangano"}. The entries of the map is its set of “key-value pairs”. The key-value pairs are called entries.

In a map, the keys must all be unique, but the values do not have to be.

There are two main types of maps:

• HashMap: Keys can be basically anything. Order of iteration is not defined (except there is a LinkedHashMap class which iterates in the order you inserted them).
• TreeMap: Keys must be comparable, and iteration is done over keys in sorted order.

Learning By Doing

// Create fixed-size, read-only (immutable) maps
Map.of("Spades", "♤", "Hearts", "♡", "Diamonds", "♢", "Clubs", "♧")
Map.of()

// Create editable maps that can grow and shrink
var m = new HashMap<String, Integer>();
var m2 = new TreeMap<String, Integer>();

// Adding and/or updating
m.put("Alice", 83);          // If Alice is not already a key, add [Alice, 83]
                             // ...but if Alice is there, then update value to 83
m.putIfAbsent("Bob", 29);    // If Bob is not already a key, add [Bob, 29]
                             // ...but if Bob is there, do nothing
m2.put("Carolyne", 70);
m2.put("Bob", 55);
m.putAll(m2)                 // m is now {Carloyne=70, Bob=55, Alice=83}
m.merge("Alice", 1, Integer::sum)
                             // m is now {Carloyne=70, Bob=55, Alice=84}

// Removing
m.remove("Carolyne");        // m is now {Bob=55, Alice=83}

// Lookup by key
m.get("Alice")               // Get corresponding value for Alice if Alice is present,
                             // ...otherwise return null
m.getOrDefault("Bob", 0)     // Get corresponding value for Alice if Alice is present,
                             // ...otherwise return 0

// Iterating
for (var e : m.entrySet()) {
    // Do something with m.getKey() and m.getValue()
}

// Printing
System.out.println(m);       // Prints {Bob=55, Alice=83}

Operations on Maps

Creating maps:

If you use Map.of, Map.copyOf, or Map.ofEntries to create a map, you won’t know what kind of map you got, so do not expect any iteration order.

These operations apply to all maps:

and if the map is mutable, you can do these:

Map.of and Map.copyOf make immutable maps. To get mutable maps we use the constructors for HashMap or TreeMap (and you can make your own maps, too, since, you guessed it, Map is an interface!). Let’s do a tiny bit of practice with JShell, first with an immutable map:

jshell> var capitals = Map.of(
   ...>     "Hhohho", "Mbabane",
   ...>     "Manzini", "Manzini",
   ...>     "Lubombo", "Siteki",
   ...>     "Shiselweni", "Nhlangano"
   ...> )

jshell> capitals.isEmpty()
false

jshell> capitals.size()
4

jshell> capitals.keySet()
[Manzini, Hhohho, Shiselweni, Lubombo]

jshell> for (var e : capitals.entrySet()) {
   ...>     System.out.println("Capital of " + e.getKey() + " is " + e.getValue());
   ...> }
Capital of Manzini is Manzini
Capital of Hhohho is Mbabane
Capital of Shiselweni is Nhlangano
Capital of Lubombo is Siteki

jshell> capitals.forEach((k,v) -> System.out.println("Capital of " + k + " is " + v))
Capital of Manzini is Manzini
Capital of Hhohho is Mbabane
Capital of Shiselweni is Nhlangano
Capital of Lubombo is Siteki

And more examples, with a mutable map:

jshell> var counts = new HashMap<String, Integer>()

jshell> counts.put("dog", 3) ; counts
{dog=3}

jshell> counts.putAll(Map.of("rat", 2, "bat", 5)) ; counts
{bat=5, rat=2, dog=3}

jshell> counts.put("rat", 10) ; counts
{bat=5, rat=10, dog=3}

jshell> counts.putIfAbsent("rat", 5) ; counts
{bat=5, rat=10, dog=3}

jshell> counts.getOrDefault("dog", 0)
3

jshell> counts.getOrDefault("cow", 0)
0

Practice more! Create your own maps and try out each of the operations above.

Word Counting

Hey, how about an example? Let’s do the famous word count application, a popular job interview question. Given a string of comma-separated words, compute case-insensitive word frequencies, and produce, as output, a little table of the words with their count, sorted by word. Since we want our output sorted, we will gather up our entries into a TreeMap, which guarantees the entries are sorted by key when read.

For fun, we’ll show how to do this two ways. This first is very direct, straightforward, step-by-step, to the point. The second uses those fancy streams. It’s probably best to learn the non-stream way first, but you should definitely eventually learn how to use streams.

import java.util.TreeMap;
import java.util.stream.Stream;
import static java.util.stream.Collectors.groupingBy;
import static java.util.stream.Collectors.counting;

public class WordCountDemo {

    public static void printWordCountsWithoutUsingStreams(String text) {
        var counts = new TreeMap<String, Integer>();
        for (var word: text.split(",")) {
            word = word.toLowerCase().trim();
            counts.put(word, counts.getOrDefault(word, 0) + 1);
        }
        for (var e : counts.entrySet()) {
          System.out.printf("%s %d\n", e.getKey(), e.getValue());
        }
    }

    public static void printWordCountsUsingStreams(String text) {
        Stream.of(text.split(","))
            .map(String::trim)
            .collect(groupingBy(String::toLowerCase, TreeMap::new, counting()))
            .forEach((word, count) -> System.out.printf("%s %d%n", word, count));
    }

    public static void main(String[] args) {
        var text = "Dog, Q,dog, raT,DOg,q,rat,ネズミ, rat,   cat,крыса,rat,rat,";
        printWordCountsUsingStreams(text);
        System.out.println("--------");
        printWordCountsWithoutUsingStreams(text);
    }
}

This application is presented only as an illustration of what can be done with Java streams. You do not have to understand it fully right now. It is far from what you would call “basic Java” but hopefully it gets you interested and motivated to study more.

Exceptions

Things can go wrong. A good way to think about programming is that every operation can succeed or fail. If it succeeds, it should return a nice value and/or perform its expected action. If it cannot properly return a value or carry out its expected action, then it should fail, and fail hard: it should throw an exception.

In these notes so far, we’ve seen a bunch of failures, among them:

• ArithmeticException for overflow
• ArithmeticException for division by zero
• ArrayIndexOutOfBoundsException when trying to access an array by an index it does not have
• UnsupportedOperationException when trying to add to an immutable list
• NullPointerException when trying to access a field or call a method on null.

And there are more just like them. (See here and here).

We’ve seen example already on this page where exceptions were thrown and where they were caught. As usual, there’s more to all this, but hopefully you have the basic idea.

When you write your own methods, you should be on the lookout for problems that may occur if your users pass you bad arguments. Here are some nice built-in exceptions that you can throw:

You may have the opportunity to write your own exception classes; doing so is outside the scope of these notes.

What’s Next

We’ve only toured the basics of the language. There’s so much more to learn. Here are few additional pages of notes:

• Java Interfaces
• Java Generics
• Java Collections
• Java Lambdas
• Java Streams
• Java Unit Testing
• Writing Large Java Programs
• Java Graphics
• Java Networking
• Java Web Servers

I know.

Most of these pages are under construction.

Finally, don’t forget the official Java development downloads, documentation, and other resources.

Summary