Java API Documentation: A Software Development Community Contributor

For those of us who regularly write code in Java or a JVM-hosted language (Groovy, JRuby, Jython, etc.), the Java Platform API documentation is a very valuable resource. In fact, it is one of the resources I most frequently access in my Java development. However, the Java API documentation's value is not limited to JVM-based development. It can, in fact, be helpful for developers writing code in programming languages that have nothing to do with the JVM (Java Virtual Machine).

An example of the value of the Java API documentation even outside of the Java ecosystem is provided in the comments on a recent DZone link to a blog posting called URI vs URL vs URN. In the comments section for both the original blog post and the DZone link to that blog post, Shawn Hartsock points out that the Javadoc-based documentation for the java.net.URI class is a useful resource in understanding the relationship of the terms URI, URL, and URN.

The concepts of URL, URI, and URN are not unique to Java. However, the documentation for the Java URI class provides about as clear, lucid, and thorough coverage of these concepts as I would want, regardless of the language that I am developing in. Included in this class's excellent documentation are references and links to the authoritative original sources on the subject (Uniform Resource Identifiers (URI): Generic Syntax [RFC2396, August 1998] and Format for Literal IPv6 Addresses in URLs [RFC2732, December 1999]). The documentation for java.net.URI provides highly detailed and specific information based on these documents and then provides this concise explanation of the relationship of URI to URL and to URN:

A URI is a uniform resource identifier while a URL is a uniform resource locator. Hence every URL is a URI, abstractly speaking, but not every URI is a URL. This is because there is another subcategory of URIs, uniform resource names (URNs), which name resources but do not specify how to locate them. The mailto, news, and isbn URIs shown above are examples of URNs.

The documentation for java.net.URI also adds that "the conceptual distinction between URIs and URLs is reflected in the differences between this class and the URL class." In other words, the differences between the two JDK classes java.net.URI and java.net.URL reflect the differences in the concepts of URI and URL. For the Java developer, the differences are modeled directly. For the non-Java developer, the classes themselves might not be useful, but their documentation certainly is useful.

The value provided by Java documentation to the general software development community is not limited to the Java SE API documentation. The Java EE API documentation contains significant information on various aspects of HTTP and other web-related technologies.

I have found the Java API documentation to be extremely helpful in my Java development. The more surprising observation, though, has come when I have found information that I am looking for on topics more general to software development. The Java documentation contributes significant technical knowledge to the general software development community.