Improve Java examples

--
MOS_MIGRATED_REVID=86787893

24 files changed, 232 insertions, 133 deletions

diff --git a/base_workspace/examples/java-native/README.md b/base_workspace/examples/java-native/README.md
new file mode 100644
index 0000000000..fb37462bf3
--- /dev/null
+++ b/base_workspace/examples/java-native/README.md
@@ -0,0 +1,4 @@
+Java Examples
+=============
+
+This directory contains examples for Java language rules.
diff --git a/base_workspace/examples/java-native/src/main/java/com/example/myproject/BUILD b/base_workspace/examples/java-native/src/main/java/com/example/myproject/BUILD
new file mode 100644
index 0000000000..717625343b
--- /dev/null
+++ b/base_workspace/examples/java-native/src/main/java/com/example/myproject/BUILD
@@ -0,0 +1,24 @@
+package(default_visibility = ["//visibility:public"])
+
+java_binary(
+    name = "hello-world",
+    main_class = "com.example.myproject.Greeter",
+    runtime_deps = [":hello-lib"],
+)
+
+java_library(
+    name = "hello-lib",
+    srcs = glob(["*.java"]),
+)
+
+java_binary(
+    name = "hello-resources",
+    main_class = "com.example.myproject.Greeter",
+    runtime_deps = [":custom-greeting"],
+)
+
+java_library(
+    name = "custom-greeting",
+    srcs = ["Greeter.java"],
+    resources = ["//examples/java-native/src/main/resources:greeting"],
+)
diff --git a/base_workspace/examples/java-native/src/main/java/com/example/myproject/Greeter.java b/base_workspace/examples/java-native/src/main/java/com/example/myproject/Greeter.java
new file mode 100644
index 0000000000..4123f2e202
--- /dev/null
+++ b/base_workspace/examples/java-native/src/main/java/com/example/myproject/Greeter.java
@@ -0,0 +1,49 @@
+package com.example.myproject;
+
+import java.io.InputStream;
+import java.io.PrintStream;
+import java.util.Scanner;
+
+/**
+ * Prints a greeting which can be customized by building with resources and/or passing in command-
+ * line arguments.
+ *
+ * <p>Building and running this file will print "Hello world". Build and run the
+ * //examples/java-native/src/main/java/com/example/myproject:hello-world target to demonstrate
+ * this.</p>
+ *
+ * <p>If this is built with a greeting.txt resource included, it will replace "Hello" with the
+ * contents of greeting.txt. The
+ * //examples/java-native/src/main/java/com/example/myproject:hello-resources target demonstrates
+ * this.</p>
+ *
+ * <p>If arguments are passed to the binary on the command line, the first argument will replace
+ * "world" in the output. See //examples/java-native/src/test/java/com/example/myproject:hello's
+ * argument test.</p>
+ */
+public class Greeter {
+  static PrintStream out = System.out;
+
+  public static String convertStreamToString(InputStream is) throws Exception {
+    try (Scanner s = new Scanner(is)) {
+      s.useDelimiter("\n");
+      return s.hasNext() ? s.next() : "";
+    }
+  }
+
+  public void hello(String obj) throws Exception {
+    String greeting = "Hello";
+    InputStream stream  = Greeter.class.getResourceAsStream(
+        "/examples/java-native/src/main/resources/greeting.txt");
+    if (stream != null) {
+      greeting = convertStreamToString(stream);
+    }
+    out.println(greeting + " " + obj);
+  }
+
+  public static void main(String... args) throws Exception {
+    Greeter g = new Greeter();
+    String obj = args.length > 0 ? args[0] : "world";
+    g.hello(obj);
+  }
+}
diff --git a/base_workspace/examples/java-native/src/main/resources/BUILD b/base_workspace/examples/java-native/src/main/resources/BUILD
new file mode 100644
index 0000000000..8347a3555a
--- /dev/null
+++ b/base_workspace/examples/java-native/src/main/resources/BUILD
@@ -0,0 +1,6 @@
+package(default_visibility = ["//visibility:public"])
+
+filegroup(
+    name = "greeting",
+    srcs = ["greeting.txt"],
+)
diff --git a/base_workspace/examples/java/greeting.txt b/base_workspace/examples/java-native/src/main/resources/greeting.txt
index 09170083fc..09170083fc 100644
--- a/base_workspace/examples/java/greeting.txt
+++ b/base_workspace/examples/java-native/src/main/resources/greeting.txt
diff --git a/base_workspace/examples/java-native/src/test/java/com/example/myproject/BUILD b/base_workspace/examples/java-native/src/test/java/com/example/myproject/BUILD
new file mode 100644
index 0000000000..838107650c
--- /dev/null
+++ b/base_workspace/examples/java-native/src/test/java/com/example/myproject/BUILD
@@ -0,0 +1,33 @@
+java_test(
+    name = "hello",
+    srcs = ["TestHello.java"],
+    deps = [
+        "//examples/java-native/src/main/java/com/example/myproject:hello-lib",
+        "//third_party:junit4",
+    ],
+)
+
+java_test(
+    name = "custom",
+    srcs = ["TestCustomGreeting.java"],
+    deps = [
+        "//examples/java-native/src/main/java/com/example/myproject:custom-greeting",
+        "//third_party:junit4",
+    ],
+)
+
+java_test(
+    name = "fail",
+    srcs = ["Fail.java"],
+    deps = ["//third_party:junit4"],
+)
+
+# This attempts to run TestCustomGreeting.java without any resources, so fails.
+java_test(
+    name = "resource-fail",
+    srcs = glob(["Test*.java"]),
+    deps = [
+        "//examples/java-native/src/main/java/com/example/myproject:hello-lib",
+        "//third_party:junit4",
+    ],
+)
diff --git a/base_workspace/examples/javatests/test/Fail.java b/base_workspace/examples/java-native/src/test/java/com/example/myproject/Fail.java
index 10e99210ff..7b947c6e96 100644
--- a/base_workspace/examples/javatests/test/Fail.java
+++ b/base_workspace/examples/java-native/src/test/java/com/example/myproject/Fail.java
@@ -1,8 +1,11 @@
-package test;
+package com.example.myproject;
 
 import org.junit.Assert;
 import org.junit.Test;
 
+/**
+ * A test that always fails.
+ */
 public class Fail {
   @Test
   public void testFail() {
diff --git a/base_workspace/examples/javatests/test/TestBye.java b/base_workspace/examples/java-native/src/test/java/com/example/myproject/TestCustomGreeting.java
index 2c00ce6e6c..f14b7d234a 100644
--- a/base_workspace/examples/javatests/test/TestBye.java
+++ b/base_workspace/examples/java-native/src/test/java/com/example/myproject/TestCustomGreeting.java
@@ -1,4 +1,4 @@
-package test;
+package com.example.myproject;
 
 import static org.junit.Assert.assertEquals;
 
@@ -8,7 +8,10 @@ import java.io.ByteArrayOutputStream;
 import java.io.PrintStream;
 import java.nio.charset.StandardCharsets;
 
-public class TestBye {
+/**
+ * Tests using a resource file to replace "Hello" in the output.
+ */
+public class TestCustomGreeting {
 
   @Test
   public void testNoArgument() throws Exception {
diff --git a/base_workspace/examples/javatests/test/TestHello.java b/base_workspace/examples/java-native/src/test/java/com/example/myproject/TestHello.java
index d121f96c27..d50e6e503f 100644
--- a/base_workspace/examples/javatests/test/TestHello.java
+++ b/base_workspace/examples/java-native/src/test/java/com/example/myproject/TestHello.java
@@ -1,4 +1,4 @@
-package test;
+package com.example.myproject;
 
 import static org.junit.Assert.assertEquals;
 
@@ -8,6 +8,12 @@ import java.io.ByteArrayOutputStream;
 import java.io.PrintStream;
 import java.nio.charset.StandardCharsets;
 
+/**
+ * Tests different numbers of arguments to main().
+ *
+ * <p>With an empty args array, {@link Greeter} should print "Hello world". If there are one or more
+ * args, {@link Greeter} should print "Hello &lt;arg[0]&gt;".</p>
+ */
 public class TestHello {
 
   @Test
diff --git a/base_workspace/examples/java-skylark/README.md b/base_workspace/examples/java-skylark/README.md
new file mode 100644
index 0000000000..970a859f54
--- /dev/null
+++ b/base_workspace/examples/java-skylark/README.md
@@ -0,0 +1,7 @@
+Skylark Java Examples
+=====================
+
+Use the native Java rules (see the examples in
+_base_workspace/examples/java-native_) for building Java, not these. These
+files are examples of how Skylark rules can be used (see
+_tools/build_rules/java_rules_skylark.bzl_ for the rule definitions).
diff --git a/base_workspace/examples/java-skylark/src/main/java/com/example/myproject/BUILD b/base_workspace/examples/java-skylark/src/main/java/com/example/myproject/BUILD
new file mode 100644
index 0000000000..ed69d7f2b3
--- /dev/null
+++ b/base_workspace/examples/java-skylark/src/main/java/com/example/myproject/BUILD
@@ -0,0 +1,21 @@
+load("tools/build_rules/java_rules_skylark", "java_library", "java_binary", "java_test")
+
+package(default_visibility = ["//visibility:public"])
+
+java_binary(
+    name = "hello-world",
+    srcs = ["Greeter.java"],
+    main_class = "com.example.myproject.Greeter",
+)
+
+java_binary(
+    name = "hello-data",
+    main_class = "com.example.myproject.Greeter",
+    deps = [":hello-lib"],
+)
+
+java_library(
+    name = "hello-lib",
+    srcs = ["Greeter.java"],
+    data = ["//examples/java-skylark/src/main/resources:greeting"],
+)
diff --git a/base_workspace/examples/java_oss/Greeter.java b/base_workspace/examples/java-skylark/src/main/java/com/example/myproject/Greeter.java
index 39aba02c97..b4d8516dc9 100644
--- a/base_workspace/examples/java_oss/Greeter.java
+++ b/base_workspace/examples/java-skylark/src/main/java/com/example/myproject/Greeter.java
@@ -1,11 +1,18 @@
-package test;
+package com.example.myproject;
 
 import java.io.FileInputStream;
 import java.io.FileNotFoundException;
 import java.io.InputStream;
+import java.io.PrintStream;
 import java.util.Scanner;
 
-class Greeter {
+/**
+ * Prints a greeting which can be customized by building with data and/or passing in command-
+ * line arguments.
+ */
+public class Greeter {
+  static PrintStream out = System.out;
+
   public static String getRunfiles() {
     String path = System.getenv("JAVA_RUNFILES");
     if (path == null) {
@@ -22,15 +29,15 @@ class Greeter {
   public void hello(String obj) throws Exception {
     String greeting = "Hello";
     try {
-      String greetFile = getRunfiles() + "/examples/java_oss/greeting.txt";
+      String greetFile = getRunfiles() + "/examples/java-skylark/src/main/resources/greeting.txt";
       greeting = convertStreamToString(new FileInputStream(greetFile));
     } catch (FileNotFoundException e) {
       // use default.
     }
-    System.out.println(greeting + " " + obj);
+    out.println(greeting + " " + obj);
   }
 
-  public static void main(String []args) throws Exception {
+  public static void main(String... args) throws Exception {
     Greeter g = new Greeter();
     String obj = args.length > 0 ? args[0] : "world";
     g.hello(obj);
diff --git a/base_workspace/examples/java-skylark/src/main/resources/BUILD b/base_workspace/examples/java-skylark/src/main/resources/BUILD
new file mode 100644
index 0000000000..8347a3555a
--- /dev/null
+++ b/base_workspace/examples/java-skylark/src/main/resources/BUILD
@@ -0,0 +1,6 @@
+package(default_visibility = ["//visibility:public"])
+
+filegroup(
+    name = "greeting",
+    srcs = ["greeting.txt"],
+)
diff --git a/base_workspace/examples/java-skylark/src/main/resources/greeting.txt b/base_workspace/examples/java-skylark/src/main/resources/greeting.txt
new file mode 100644
index 0000000000..17654db5a1
--- /dev/null
+++ b/base_workspace/examples/java-skylark/src/main/resources/greeting.txt
@@ -0,0 +1 @@
+Heyo
diff --git a/base_workspace/examples/java-skylark/src/test/java/com/example/myproject/BUILD b/base_workspace/examples/java-skylark/src/test/java/com/example/myproject/BUILD
new file mode 100644
index 0000000000..90e71f97ac
--- /dev/null
+++ b/base_workspace/examples/java-skylark/src/test/java/com/example/myproject/BUILD
@@ -0,0 +1,16 @@
+load("tools/build_rules/java_rules_skylark", "java_test")
+
+java_test(
+    name = "pass",
+    srcs = ["TestHello.java"],
+    deps = [
+        "//examples/java-skylark/src/main/java/com/example/myproject:hello-lib",
+        "//third_party:junit4",
+    ],
+)
+
+java_test(
+    name = "fail",
+    srcs = ["Fail.java"],
+    main_class = "com.example.myproject.Fail",
+)
diff --git a/base_workspace/examples/java_oss/Fail.java b/base_workspace/examples/java-skylark/src/test/java/com/example/myproject/Fail.java
index 61e253930c..079e1e9f04 100644
--- a/base_workspace/examples/java_oss/Fail.java
+++ b/base_workspace/examples/java-skylark/src/test/java/com/example/myproject/Fail.java
@@ -1,4 +1,4 @@
-package test;
+package com.example.myproject;
 
 class Fail {
   public static void main(String []args) {
diff --git a/base_workspace/examples/java-skylark/src/test/java/com/example/myproject/TestHello.java b/base_workspace/examples/java-skylark/src/test/java/com/example/myproject/TestHello.java
new file mode 100644
index 0000000000..d50e6e503f
--- /dev/null
+++ b/base_workspace/examples/java-skylark/src/test/java/com/example/myproject/TestHello.java
@@ -0,0 +1,35 @@
+package com.example.myproject;
+
+import static org.junit.Assert.assertEquals;
+
+import org.junit.Test;
+
+import java.io.ByteArrayOutputStream;
+import java.io.PrintStream;
+import java.nio.charset.StandardCharsets;
+
+/**
+ * Tests different numbers of arguments to main().
+ *
+ * <p>With an empty args array, {@link Greeter} should print "Hello world". If there are one or more
+ * args, {@link Greeter} should print "Hello &lt;arg[0]&gt;".</p>
+ */
+public class TestHello {
+
+  @Test
+  public void testNoArgument() throws Exception {
+    ByteArrayOutputStream out = new ByteArrayOutputStream();
+    Greeter.out = new PrintStream(out);
+    Greeter.main();
+    assertEquals("Hello world\n", new String(out.toByteArray(), StandardCharsets.UTF_8));
+  }
+
+  @Test
+  public void testWithArgument() throws Exception {
+    ByteArrayOutputStream out = new ByteArrayOutputStream();
+    Greeter.out = new PrintStream(out);
+    Greeter.main("toto");
+    assertEquals("Hello toto\n", new String(out.toByteArray(), StandardCharsets.UTF_8));
+  }
+
+}
diff --git a/base_workspace/examples/java/BUILD b/base_workspace/examples/java/BUILD
deleted file mode 100644
index 09e671be81..0000000000
--- a/base_workspace/examples/java/BUILD
+++ /dev/null
@@ -1,25 +0,0 @@
-package(default_visibility = ["//visibility:public"])
-
-java_library(
-    name = "bye-lib",
-    srcs = ["test/Greeter.java"],
-    resources = ["greeting.txt"],
-)
-
-java_library(
-    name = "hello-lib",
-    srcs = ["test/Greeter.java"],
-)
-
-java_binary(
-    name = "bye-world",
-    main_class = "test.Greeter",
-    runtime_deps = [":bye-lib"],
-)
-
-java_binary(
-    name = "hello-world",
-    main_class = "test.Greeter",
-    runtime_deps = [":hello-lib"],
-)
-
diff --git a/base_workspace/examples/java/test/Greeter.java b/base_workspace/examples/java/test/Greeter.java
deleted file mode 100644
index e1eebe7960..0000000000
--- a/base_workspace/examples/java/test/Greeter.java
+++ /dev/null
@@ -1,31 +0,0 @@
-package test;
-
-import java.io.InputStream;
-import java.io.PrintStream;
-import java.util.Scanner;
-
-class Greeter {
-  static PrintStream out = System.out;
-
-  public static String convertStreamToString(InputStream is) throws Exception {
-    try (Scanner s = new Scanner(is)) {
-      s.useDelimiter("\n");
-      return s.hasNext() ? s.next() : "";
-    }
-  }
-
-  public void hello(String obj) throws Exception {
-    String greeting = "Hello";
-    InputStream stream  = Greeter.class.getResourceAsStream("/greeting.txt");
-    if (stream != null) {
-      greeting = convertStreamToString(stream);
-    }
-    out.println(greeting + " " + obj);
-  }
-
-  public static void main(String... args) throws Exception {
-    Greeter g = new Greeter();
-    String obj = args.length > 0 ? args[0] : "world";
-    g.hello(obj);
-  }
-}
diff --git a/base_workspace/examples/java_oss/BUILD b/base_workspace/examples/java_oss/BUILD
deleted file mode 100644
index a4acd5ce5f..0000000000
--- a/base_workspace/examples/java_oss/BUILD
+++ /dev/null
@@ -1,33 +0,0 @@
-load("tools/build_rules/java_rules_oss", "java_library", "java_binary", "java_test")
-
-java_library(
-    name = "hello-lib",
-    srcs = ["Greeter.java"],
-    data = ["greeting.txt"],
-)
-
-java_binary(
-    name = "hello-world",
-    main_class = "test.Greeter",
-    deps = [":hello-lib"],
-)
-
-java_binary(
-    name = "hello-main",
-    srcs = ["Greeter.java"],
-    main_class = "test.Greeter",
-)
-
-# Testing.
-
-java_test(
-    name = "pass_test",
-    main_class = "test.Greeter",
-    deps = [":hello-lib"],
-)
-
-java_test(
-    name = "fail_test",
-    srcs = ["Fail.java"],
-    main_class = "test.Fail",
-)
diff --git a/base_workspace/examples/java_oss/greeting.txt b/base_workspace/examples/java_oss/greeting.txt
deleted file mode 100644
index 3f453d002f..0000000000
--- a/base_workspace/examples/java_oss/greeting.txt
+++ /dev/null
@@ -1 +0,0 @@
-Hail
diff --git a/base_workspace/examples/javatests/BUILD b/base_workspace/examples/javatests/BUILD
deleted file mode 100644
index c504b1c7a0..0000000000
--- a/base_workspace/examples/javatests/BUILD
+++ /dev/null
@@ -1,32 +0,0 @@
-java_test(
-    name = "hello",
-    srcs = ["test/TestHello.java"],
-    deps = [
-        "//examples/java:hello-lib",
-        "//third_party:junit4",
-    ],
-)
-
-java_test(
-    name = "bye",
-    srcs = ["test/TestBye.java"],
-    deps = [
-        "//examples/java:bye-lib",
-        "//third_party:junit4",
-    ],
-)
-
-java_test(
-    name = "fail",
-    srcs = ["test/Fail.java"],
-    deps = ["//third_party:junit4"],
-)
-
-java_test(
-    name = "should_fail",
-    srcs = glob(["test/Test*.java"]),
-    deps = [
-        "//examples/java:hello-lib",
-        "//third_party:junit4",
-    ],
-)
diff --git a/src/test/java/BUILD b/src/test/java/BUILD
index 1dfc4af8fc..51b5ab5d92 100644
--- a/src/test/java/BUILD
+++ b/src/test/java/BUILD
@@ -86,7 +86,7 @@ java_test(
             "vfs/*.java",
             "vfs/inmemoryfs/*.java",
         ]],
-        # java_rules_oss doesn't support resource loading with
+        # java_rules_skylark doesn't support resource loading with
         # qualified paths.
         exclude = [
             test_prefix + f
diff --git a/tools/build_rules/java_rules_oss.bzl b/tools/build_rules/java_rules_skylark.bzl
index dcd2329ebc..dcd2329ebc 100644
--- a/tools/build_rules/java_rules_oss.bzl
+++ b/tools/build_rules/java_rules_skylark.bzl