The first preview release of the Java EE 6 Tutorial was released yesterday.
Get it by installing the Java EE 6 SDK Preview and ugprading the Java EE 6 Tutorial package using the Update Tool.
We've got a bunch of new material and examples in this release, including:
- JavaServer Faces 2.0, including Facelets, an XHTML-based display technology that is much easier than JSP.
- JAX-RS 1.1, the RESTful web services API.
- EJB 3.1, which really simplifies EJB development, and allows you to package enterprise beans within web applications.
- The Java Persistence API 2.0, with support for collections (including Maps) within entities, mixed field/property access, and orphan removal for one-to-many and one-to-one relationships.
- Servlet 3.0, which now uses annotations to truly make the web.xml deployment descriptor optional.
Our examples are developed as a java.net project, so if you find bugs or want to file enhancement requests we'd love to hear about them.
Our mailing lists provide another way of giving feedback, and are also good places to start if you're interested in contributing source code or material for the Java EE 6 Tutorial.
With the help of the excellent media team here at Sun, I recorded a screencast screencast demonstrating how to deploy and run the ClickToDial sample application on Project SailFin, aka GlassFish Communications Server.
To follow along with the screencast, you'll need the following software:
- SailFin
Milestone 41.5, available at the SailFin project home page. - The NetBeans
6.o IDE, or the newly release 6.16.5, available at netbeans.org. - The SIP Servlet 1.1 version of
ClickToDial. - The XLite 3.0 softphone, available for free download at Counterpath's web site.
Here's a downloadable offline version of the screencast.
Edit: New link with screencast controls.
Edit: I updated the screencast and the example code to use SIP Servlet 1.1 (JSR 289) features.
Some users have had build errors similar to the following:
BUILD FAILED
C:\sun\swdp-tutorial\swdp-tutorial\swdp-tutorial-2.0\examples\rome\atom-feed\build.xml:8:
The following error occurred while executing this line:
C:\sun\swdp-tutorial\swdp-tutorial\swdp-tutorial-2.0\examples\bp-project\main.xml:28:
The following error occurred while executing this line:
C:\sun\swdp-tutorial\swdp-tutorial\swdp-tutorial-2.0\examples\bp-project\webpack-ant.xml:28:
C:\sun\glassfish\domains\${javaee.domain}\lib not found
This error is caused by the javaee.domain property not being set, usually because you haven't completed the configuration of the tutorial as detailed in the SWDP Tutorial 2.0's preface.
Briefly, you should rename:
.../swdp-tutorial-2.0/examples/bp-project/build.properties.sample
to:
.../swdp-tutorial-2.0/examples/bp-project/build.properties
and set the properties to match your environment. javaee.domain is initally set to domain1, the GlassFish default domain, so you should only change it if you changed the domain in which you installed the SWDP JARs in the SWDP installer.
Tim Bray's remarks on the death of documentation are typical of many engineers I've encountered over the years. For example, the chief architect at an application server company I used to work for thought that documentation was a symptom of incomplete or unintuitive tools. That is, the existence of documentation was an engineering flaw, and that a sufficiently well designed piece of software would not require any explanation.
Tim Bray's thinking is not quite so extreme, but the assumption is similar: coordinated documentation efforts are hopelessly flawed endeavors. Why not cut out the middleman and just have the users and engineers write the documentation, in the form of a Wiki where problems could be posted and solutions contributed for all to see?
I should point out that Udell's article was about solving the problem of technical support docs, but Bray picked up a few overtones in the article about documentation in general being crappy and sort of ran with it.
Personally, I fail to see the necessity of an excluded middle here.
First of all, the set of products or pieces of software that could be documented completely through a user-written Wiki isn't very large, because the product/tool needs to be fairly simple for a tabula rasa user to even know where to start with it.
Secondly, although I find Google and mailing list questions and forum postings quite useful for solving specific problems, these little snippets of information do not make a coherent whole. A related point is that the people posting the questions are often familiar with the system generally, in fact are expected to be familiar with the system, and are having problems with a particular area. What is the standard response to newbies who post general questions like: How does $PRODUCT work? RTFM.
Thirdly, the probable success of shunting the responsibility of writing doc onto the users, with contributions from engineers, is highly unlikely, to put it mildly. Somebody has to do the thankless job of writing this crap, engineers rarely have time to even review the material produced by doc teams (to say nothing of actually doing it themselves), and there is something to be said for coherent, grammatical, and style-checked prose when using ever-more-complex technology.
So, I'll conclude with a proposal that is hopefully obvious when you think about it: Wouldn't it make more sense to deliver the documentation in a format that could accomodate general discussion of the system as well as user supplied questions and answers? Merge the manual with the Wiki, yo? Some projects do this, like the PHP docs online and the PostgreSQL docs.
