Java Copy Constructor: Duplicating Objects Safely

// Shows shallow copying, deep copying, and why clone() is avoided.
// String-aware comments are stripped before the structural checks run.
public class CopyConstructorDemo {
    private static final int FIRST_ITEM = 0;
    private static final String BOOK = "book";
    private static final String LAMP = "lamp";
    private static final String PEN = "pen";
    // A MUTABLE NESTED TYPE, which is where sharing becomes dangerous
    public static class Line {
        private String sku;
        private int quantity;
        public Line(String sku, int quantity) {
            this.sku = sku;
            this.quantity = quantity;
        } public Line(Line other) {
            this.sku = other.sku;
            this.quantity = other.quantity;
        } public void setQuantity(int quantity) {
            this.quantity = quantity;
        } public int getQuantity() {
            return quantity;
        } @Override public String toString() {
            return sku + " x" + quantity;
        }
    } // THE SHALLOW COPY, which is what most people write by mistake
    public static class ShallowOrder {
        private final String reference;
        final List<Line> lines = new ArrayList<>();
        public ShallowOrder(String reference) {
            this.reference = reference;
            this.lines.add(new Line(BOOK, 1));
        } public ShallowOrder(ShallowOrder other) {
            this.reference = other.reference;
            // The list reference is copied, so both orders share ONE list
            this.lines.addAll(other.lines);
        } public List<Line> getLines() {
            return lines;
        }
    } // THE DEEP COPY, which allocates a new list and new Line objects
    public static class Order {
        private final String reference;
        private final List<Line> lines;
        public Order(String reference) {
            this.reference = reference;
            this.lines = new ArrayList<>();
            this.lines.add(new Line(BOOK, 1));
        } // LEVEL ONE creates a new container, LEVEL TWO copies the elements
        public Order(Order other) {
            this.reference = other.reference;
            this.lines = new ArrayList<>();
            for (Line line : other.lines) {
                this.lines.add(new Line(line));
            }
        } public List<Line> getLines() {
            return List.copyOf(lines);
        } public void addLine(Line line) {
            lines.add(line);
        }
    } // AN IMMUTABLE FIELD NEEDS NO SPECIAL TREATMENT
    public static class Tag {
        private final String label;
        public Tag(String label) {
            this.label = label;
        } public Tag(Tag other) {
            this.label = other.label;
        } public String getLabel() {
            return label;
        }
    } // ARRAY FIELDS NEED clone, AND EACH LEVEL NEEDS ITS OWN clone
    public static class Grid {
        private final int[][] cells;
        public Grid(int[][] cells) {
            this.cells = cells;
        } public Grid(Grid other) {
            this.cells = new int[other.cells.length][];
            for (int row = FIRST_ITEM;
            row < other.cells.length;
            row++) {
                this.cells[row] = other.cells[row].clone();
            }
        } public void bump(int row, int column) {
            cells[row][column] = cells[row][column] + 1;
        } public int get(int row, int column) {
            return cells[row][column];
        }
    } public static void main(String[] args) {
        // A SHALLOW COPY SHARES STATE, so the original is changed underneath us
        ShallowOrder shallowOriginal = new ShallowOrder("SO-1");
        ShallowOrder shallowCopy = new ShallowOrder(shallowOriginal);
        shallowCopy.getLines().get(FIRST_ITEM).setQuantity(99);
        System.out.println("shallow original: " + shallowOriginal.getLines().get(FIRST_ITEM));
        System.out.println("shallow copy:    " + shallowCopy.getLines().get(FIRST_ITEM));
        System.out.println("same list object: " +(shallowOriginal.getLines() == shallowCopy.getLines()));
        // A DEEP COPY IS FULLY INDEPENDENT
        Order deepOriginal = new Order("SO-2");
        Order deepCopy = new Order(deepOriginal);
        deepCopy.addLine(new Line(LAMP, 2));
        deepCopy.addLine(new Line(PEN, 3));
        System.out.println("deep original count: " + deepOriginal.getLines().size());
        System.out.println("deep copy count:    " + deepCopy.getLines().size());
        System.out.println("deep original line: " + deepOriginal.getLines().get(FIRST_ITEM));
        // EACH LEVEL OF A 2D ARRAY MUST BE CLONED SEPARATELY
        Grid grid = new Grid(new int[][] {
{
                1, 2
            }, {
                3, 4
            }
        });
        Grid gridCopy = new Grid(grid);
        gridCopy.bump(FIRST_ITEM, 0);
        System.out.println("grid:        " + grid.get(FIRST_ITEM, 0));
        System.out.println("grid copy:   " + gridCopy.get(FIRST_ITEM, 0));
        // SHARING AN IMMUTABLE FIELD IS HARMLESS
        Tag tag = new Tag("priority");
        Tag tagCopy = new Tag(tag);
        System.out.println("tag: " + tag.getLabel() + " / " + tagCopy.getLabel());
        /*
            ACTUAL OUTPUT:

                shallow original: book x99
                shallow copy:    book x99
                same list object: true
                deep original count: 1
                deep copy count:    3
                deep original line: book x1
                grid:        1
                grid copy:   2
                tag: priority / priority

            THE SIX RULES THAT MATTER MOST
            1) A COPY CONSTRUCTOR IS JUST A CONSTRUCTOR TAKING ITS OWN
               TYPE. There is no keyword, so overload resolution picks
               it exactly like any other constructor.
            2) PRIMITIVES ARE COPIED BY VALUE, REFERENCES BY ADDRESS.
               Copying a field is therefore never the same as copying
               the object it points to.
            3) A SHALLOW COPY STILL SHARES MUTABLE STATE. Changing the
               copy through a shared list changes the original, and
               neither the compiler nor the runtime complains.
            4) new ArrayList<>(other) COPIES ONLY THE CONTAINER.
               Deep copying a list of mutable elements also requires
               copying each element, usually by calling its own copy
               constructor in a loop.
            5) IMMUTABLE FIELDS NEED NO COPYING. Strings, boxed values,
               and Optional are safe to share, so copying them wastes
               both time and memory.
            6) SUBCLASSES DO NOT INHERIT COPY CONSTRUCTORS. super accepts
               a parent-typed argument, but the subclass-typed overload
               needs an explicit cast or an added constructor.

            WHY clone() IS AVOIDED ENTIRELY
            IT BYPASSES EVERY CONSTRUCTOR, so the superclass chain never
            runs and inherited invariants are not established. It also
            throws a checked exception, always returns Object so the
            caller must cast, and is forbidden from assigning final
            fields because it skips initialisation altogether.
        */
    }
}