Fill in a small amount of details on the jib-as-a-library proposal

proposals/jib_core_library.md

@@ -8,12 +8,19 @@ Design for Jib Core as a Java library for building container images.
 
 # Proposed API
 
+## General Containers
+
 `Jib` - the main entrypoint for using Jib Core
+
 - `JibContainerBuilder from(String baseImageReference)`
 - `JibContainerBuilder from(ImageReference baseImageReference)`
 - `JibContainerBuilder from(RegistryImage baseImage)`
+- `static Containerizer to(RegistryImage)`
+- `static Containerizer to(DockerDaemonImage)`
+- `static Containerizer to(TarImage)`
 
 `JibContainerBuilder` - configures the container to build
+
 - `JibContainerBuilder addLayer(List<Path> files, Path pathInContainer)`
 - `JibContainerBuilder addLayer(LayerConfiguration)`
 - `JibContainerBuilder setLayers(List<LayerConfiguration>/LayerConfiguration...)`
@@ -31,46 +38,67 @@ Design for Jib Core as a Java library for building container images.
 Three `TargetImage` types (`RegistryImage`, `DockerDaemonImage`, and `TarImage`) define the 3 different targets Jib can build to.
 
 `RegistryImage` - builds to a container registry
+
 - `static RegistryImage named(ImageReference/String)`
 - `RegistryImage addCredential(String username, String password)`
 - `RegistryImage addCredentialRetriever(CredentialRetriever)`
 
 `DockerDaemonImage` - builds to a Docker daemon
+
 - `static DockerDaemonImage named(ImageReference/String)`
 - `DockerDaemonImage setDockerExecutable(Path)`
 
 `TarImage` - builds to a tarball archive
+
 - `Builder`
   - `TarImage saveTo(Path outputFile)`
 - `static Builder named(ImageReference/String)`
 
 `Containerizer` - configures how and where to containerize to
-- `static Containerizer to(RegistryImage)`
-- `static Containerizer to(DockerDaemonImage)`
-- `static Containerizer to(TarImage)`
 - `Containerizer setExecutorService(ExecutorService)`
 - `Containerizer setCacheConfiguration(CacheConfiguration)`
 - `Containerizer setEventHandlers(EventHandlers)`
 
-## For Java containers
+## Simple example
+
+```java
+Jib.from("busybox")
+   // TODO: this doesn't seem right, especially if multiple files are in the .addLayer call (are they cat'ed, or is /helloworld.sh a directory?)
+   .addLayer(Arrays.asList(Paths.get("helloworld.sh")), "/helloworld.sh") 
+   .setEntrypoint("/helloworld.sh")
+   .containerize(
+       Jib.to(RegistryImage.named("coollog/jibtestimage")
+                           .setCredential("coollog", "notmyrealpassword")));
+```
+
+# For Java containers
+
+`JavaContainerBuilder` - builds a `JibContainerBuilder` for Java apps. 
 
-`JavaContainerBuilder` - builds a `JibContainerBuilder` for Java apps
 - `static JavaContainerBuilder builder()`
 - `JavaContainerBuilder addDependencies(List<Path> dependencyFiles)`
 - `JavaContainerBuilder addResources(List<Path> resourceFiles)`
 - `JavaContainerBuilder addClasses(List<Path> classFiles)`
 - `JavaContainerBuilder addToClasspath(List<Path> otherFiles)`
 - `JavaContainerBuilder setJvmFlags(List<String>/String... jvmFlags)`
 - `JavaContainerBuilder setMainClass(String mainClass)`
-- `JavaContainerBuilder toContainerBuilder()`
+- `JibContainerBuilder toContainerBuilder()`
 
-# Simple example
+  Returns a `JibContainerBuilder` that, when built, will produce a minimal Java image that executes the java application specified by the builder methods previously called on this `JavaContainerBuilder`. 
 
-```java
-Jib.from("busybox")
-   .addLayer(Arrays.asList(Paths.get("helloworld.sh")), "/helloworld.sh")
-   .setEntrypoint("/helloworld.sh")
-   .containerize(
-       Jib.to(RegistryImage.named("coollog/jibtestimage")
-                           .setCredential("coollog", "notmyrealpassword"));
-```
+  Example:
+
+  ```java
+  	RegistryImage destination = RegistryImage.named("gcr.io/myuser/my-java-container:latest");
+
+    JibContainerBuilder javaImage = JavaContainerBuilder.builder()
+      .addDependencies(Lists.newArrayList(Paths.get("/my/filesystem/lib/my-dependency.jar")))      
+      .addClasses(Lists.newArrayList(Paths.get("/my/filesystem/target/com/google/FooMain.class")))
+      .setMainClass("com.google.FooMain")
+      .toContainerBuilder()
+      // Add other customization to the image, maybe some labels
+      .addExposedPort(Port.tcp(8080));
+
+    // Throws an exception if the image couldn't be build.
+    JibContainer result = javaImage.containerize(Jib.to(destination));
+  ```