diff --git a/java/deprecated.md b/java/deprecated.md
new file mode 100644
index 000000000000..8416d2c909ed
--- /dev/null
+++ b/java/deprecated.md
@@ -0,0 +1,3 @@
+This image is officially deprecated in favor of [the `openjdk` image](https://hub.docker.com/_/openjdk/), and will receive no further updates after 2016-12-31 (Dec 31, 2016). Please adjust your usage accordingly.
+
+The image has been OpenJDK-specific since it was first introduced, and as of 2016-08-10 we also have [an `ibmjava` image](https://hub.docker.com/_/ibmjava/), which made it even more clear that each repository should represent one upstream instead of one language stack or community, so this rename reflects that clarity appropriately.
diff --git a/openjdk/README-short.txt b/openjdk/README-short.txt
new file mode 100644
index 000000000000..fd22f6f13430
--- /dev/null
+++ b/openjdk/README-short.txt
@@ -0,0 +1 @@
+OpenJDK is an open-source implementation of the Java Platform, Standard Edition
diff --git a/openjdk/content.md b/openjdk/content.md
new file mode 100644
index 000000000000..59ef0323d4e9
--- /dev/null
+++ b/openjdk/content.md
@@ -0,0 +1,40 @@
+# What is OpenJDK?
+
+OpenJDK (Open Java Development Kit) is a free and open source implementation of the Java Platform, Standard Edition (Java SE). OpenJDK is the official reference implementation of Java SE since version 7.
+
+> [wikipedia.org/wiki/OpenJDK](http://en.wikipedia.org/wiki/OpenJDK)
+
+Java is a registered trademark of Oracle and/or its affiliates.
+
+%%LOGO%%
+
+# How to use this image
+
+## Start a Java instance in your app
+
+The most straightforward way to use this image is to use a Java container as both the build and runtime environment. In your `Dockerfile`, writing something along the lines of the following will compile and run your project:
+
+```dockerfile
+FROM %%REPO%%:7
+COPY . /usr/src/myapp
+WORKDIR /usr/src/myapp
+RUN javac Main.java
+CMD ["java", "Main"]
+```
+
+You can then run and build the Docker image:
+
+```console
+$ docker build -t my-java-app .
+$ docker run -it --rm --name my-running-app my-java-app
+```
+
+## Compile your app inside the Docker container
+
+There may be occasions where it is not appropriate to run your app inside a container. To compile, but not run your app inside the Docker instance, you can write something like:
+
+```console
+$ docker run --rm -v "$PWD":/usr/src/myapp -w /usr/src/myapp %%REPO%%:7 javac Main.java
+```
+
+This will add your current directory as a volume to the container, set the working directory to the volume, and run the command `javac Main.java` which will tell Java to compile the code in `Main.java` and output the Java class file to `Main.class`.
diff --git a/openjdk/github-repo b/openjdk/github-repo
new file mode 100644
index 000000000000..d690c73a8ee5
--- /dev/null
+++ b/openjdk/github-repo
@@ -0,0 +1 @@
+https://github.com/docker-library/openjdk
diff --git a/openjdk/license.md b/openjdk/license.md
new file mode 100644
index 000000000000..3a5a5a10c53d
--- /dev/null
+++ b/openjdk/license.md
@@ -0,0 +1 @@
+View [license information](http://openjdk.java.net/legal/gplv2+ce.html) for the software contained in this image.
diff --git a/openjdk/logo.png b/openjdk/logo.png
new file mode 100644
index 000000000000..30b690527813
Binary files /dev/null and b/openjdk/logo.png differ