Packages

src/SUMMARY.md

@@ -409,11 +409,24 @@
   - [Disambiguation](./inner_classes/disambiguation.md)
   - [The anonymous main class](./inner_classes/the_anonymous_main_class.md)
   - [Static Inner Classes](./inner_classes/static_inner_classes.md)
+  - [Private Inner Classes](./inner_classes/private_inner_classes.md)
 - [Packages](./packages.md)
-  - [The Default Package]()
-  - [Import]()
-  - [Import Static Methods]()
-  - [Import Inner Classes]()
+  - [Declaration](./packages/declaration.md)
+  - [Visibility](./packages/visibility.md)
+  - [Public Classes](./packages/public_classes.md)
+  - [Fully Qualified Class Name](./packages/fully_qualified_class_name.md)
+  - [Import](./packages/import.md)
+  - [The Default Package](./packages/the_default_package.md)
+  - [The anonymous main class](./packages/the_anonymous_main_class.md)
+  - [Public Methods](./packages/public_methods.md)
+  - [Package-Private Methods](./packages/package_private_methods.md)
+  - [Public Fields](./packages/public_fields.md)
+  - [Package-Private Fields](./packages/package_private_fields.md)
+  - [The Default Constructor](./packages/the_default_constructor.md)
+  - [Public Constructors](./packages/public_constructors.md)
+  - [Package-Private Constructors](./packages/package_private_constructors.md)
+  - [Subpackages](./packages/subpackages.md)
+  - [Reverse Domain Name Notation](./packages/reverse_domain_name_notation.md)
 
 - [Visibility II](./visibility_ii.md)
   - [Public Classes]()
@@ -422,7 +435,6 @@
   - [Package-Private Methods]()
   - [Public Fields]()
   - [Package-Private Fields]()
-  - [Private Inner Classes]()
 
 # Interactive Programs III
 

src/inner_classes/private_inner_classes.md

@@ -0,0 +1,20 @@
+# Private Inner Classes
+
+Both `static` and regular inner classes can be marked as `private`.
+
+```java
+class Human {
+    // No other class can see this human's thoughts
+    private class Thoughts {
+
+    }
+
+    // Nor can they see their feelings
+    private static class Feelings {
+
+    }
+}
+```
+
+Within the class they are defined, a private inner class works as normal. The
+difference is that code outside the class cannot make instances of them.

src/inner_classes/scope.md

@@ -39,4 +39,23 @@ class Main {
     }
 }
 ```
-One mental model for this is that
+One mental model for this is that its as if the inner class
+holds a reference to the one it was created in.
+
+```java,no_run
+class Car {
+    int speed = 0;
+}
+
+class CarSpeedometer {
+    private final Car madeBy;
+
+    CarSpeedometer(Car madeBy) {
+        this.madeBy = madeBy;
+    }
+
+    int getSpeed() {
+        return madeBy.speed;
+    }
+}
+```

src/inner_classes/static_inner_classes.md

@@ -30,4 +30,8 @@ class Car {
 ```
 
 I would wager that this is the most common kind of inner class to see
-in real code.
+in real code, despite requiring more words to define[^theme].
+
+[^theme]: A theme that will start to emerge is that the "best" code sometimes has
+a few extra modifiers on it and the "default" behavior isn't what you want. Static
+inner classes are way less magic.

src/packages.md

@@ -2,4 +2,13 @@
 
 Every class in Java "lives" in a package.
 
-A package is a way to group individual classes.
+A package is a way to group individual classes.
+
+```java,no_run
+package dungeon;
+
+class BugBear {
+
+}
+```
+

src/packages/declaration.md

@@ -0,0 +1,31 @@
+# Declaration
+
+To put a class into a package you need to do two things.
+
+First, put a "package declaration" at the top of the file. This looks like the word `package` followed by the name of the package and a `;`
+
+```java,no_run
+package dungeon;
+
+class BugBear {
+
+}
+```
+
+Then you need to make sure that the `.java` file is in a folder matching the name of
+that package.
+
+So, for the example above, if your code was previously laid out like this
+
+```
+src/
+   BugBear.java
+```
+
+It needs to be changed to this.
+
+```
+src/
+  dungeon/
+    BugBear.java
+```

src/packages/fully_qualified_class_name.md

@@ -0,0 +1,29 @@
+# Fully Qualified Class Name
+
+In order to use a public class from a different package you can
+write out the "fully qualified class name."[^fqcn]
+
+This is the name of the class prefixed with the package it is in.
+
+```java,no_run
+package village;
+
+public class Villager {}
+```
+
+```java,no_run
+package dungeon;
+
+class Dwarf {
+    // Works because we write out the full name
+    // and because Villager is public.
+    village.Villager meet() {
+        return new village.Villager();
+    }
+}
+```
+
+This hints that the "real name" of a class isn't what you write after `class`, but instead both that and the package name glued together.
+
+[^fqcn]: People also often call this the "FQCN". Its a fun acronym to write, but I
+have no clue how to say it out loud. "Faquacün?"

src/packages/import.md

@@ -0,0 +1,28 @@
+# Import
+
+If you don't want to write out the fully qualified class name everywhere, and few do,
+then you can use an `import`.
+
+To import a class you write `import` followed by the fully qualified class name.
+This makes it so that the "simple" class name will be usable.
+
+```java,no_run
+package village;
+
+public class Villager {}
+```
+
+```java,no_run
+package dungeon;
+
+// For the rest of the file, you can
+// just write "Villager" and Java will know
+// what you mean.
+import village.Villager;
+
+class Dwarf {
+    Villager meet() {
+        return new Villager();
+    }
+}
+```

src/packages/package_private_constructors.md

@@ -0,0 +1,28 @@
+# Package-Private Constructors
+
+A constructor without any other modifier is "package-private" in the
+same way as methods and fields.[^private]
+
+```java
+package dungeon;
+
+public class Slime {
+    final int size;
+
+    // This constructor is public, 
+    // code in other packages can use it.
+    public Slime() {
+        this.size = 5;
+    }
+
+    // This constructor is package-private,
+    // code in other packages cannot use it.
+    Slime(int size) {
+        this.size = size;
+    }
+}
+```
+
+[^private]: Your spider-sense might be tingling wondering if `private` constructors
+are a thing. They are! I'll talk about them more in-depth later, but they can be
+surprisingly useful.

src/packages/package_private_fields.md

@@ -0,0 +1,13 @@
+# Package-Private Fields
+
+Fields that are marked neither `public` nor `private` are "package-private."
+
+```java
+package village;
+
+public class Well {
+    // Neither of these can be used outside of the "village" package
+    static final int NUMBER_OF_DEMONS = 4;
+    boolean exorcismPerformed;
+}
+```

src/packages/package_private_methods.md

@@ -0,0 +1,22 @@
+# Package-Private Methods
+
+If a method is neither `public` or `private` then it can
+be used only by code in the same package.
+
+We call these methods "package-private" because they are
+"private" to code outside the package.
+
+```java
+package village;
+
+public class Villager {
+    void isNotVisible() {
+        System.out.println("""
+            This method can be called from code in the "village"
+            package, but not from other packages.
+            """);
+    }
+}
+```
+
+Which again applies to static methods as well.

src/packages/public_classes.md

@@ -0,0 +1,11 @@
+# Public Classes
+
+To be able to use a class in one package from a different package,
+you must first mark that class as `public`.
+
+```java,no_run
+package village;
+
+// Now other packages will be able to see it
+public class Villager {}
+```

src/packages/public_constructors.md

@@ -0,0 +1,35 @@
+# Public Constructors
+
+For a constructor you write to be usable across packages[^youguessed] it needs
+to be marked `public`.
+
+```java,no_run
+package dungeon;
+
+public class Skeleton {
+    public final int bones;
+
+    public Skeleton() {
+        this.bones = 206;
+    }
+}
+```
+
+```java,no_run
+package village;
+
+import dungeon.Skeleton;
+
+class Main {
+    void main() {
+        // Now this works
+        var skeleton = new Skeleton();
+
+        // And we get the right number of bones!
+        System.out.println(skeleton.bones);
+    }
+}
+```
+
+
+[^youguessed]: You guessed it!

src/packages/public_fields.md

@@ -0,0 +1,14 @@
+# Public Fields
+
+Similarly to methods, for a field to be used from a different package
+it must be marked `public`.
+
+```java
+package village;
+
+public class Well {
+    // Both of these you can use from a different package
+    public static final int DEPTH = 10;
+    public int remainingWater;
+}
+```

src/packages/public_methods.md

@@ -0,0 +1,34 @@
+# Public Methods
+
+Even though a class might itself be marked `public`, the methods
+within it will not be unless they are also `public`.
+
+```java,no_run
+package village;
+
+// Now other packages will be able to see it
+public class Villager {
+    public void isVisible() {
+        System.out.println("This method is callable from another package.");
+    }
+
+    void isNotVisible() {
+        System.out.println("This method is not.")
+    }
+}
+```
+
+This applies also to static methods.
+
+```java,no_run
+package village;
+
+public class Well {
+    public static int drawWater() {
+        System.out.println("""
+            You need this to be both public and static to
+            be able to write "Well.drawWater()"
+            """);
+    }
+}
+```