Java Reference
In-Depth Information
Many JSRs actually contain the full package documentation in HTML from Javadoc;
some JSRs, such as JSR 135, provide
all
of their information in that form. Consequently,
to use the information in a JSR successfully, you need both some domain experience
about the problem the JSR is trying to solve, as well as a clear understanding of the
packages the JSR defines and the classes those packages contain.
JSRs themselves have a clear life cycle, which includes the following phases:
1.
Draft
: JSRs frequently undergo several early drafts, many of which are reviewed
privately by the expert group that puts forth a JSR. During this phase, you may not
even know that the JSR exists; if you do, you must recognize that its contents will
almost certainly change at some point in the future.
2.
Public review
: During this time, anyone may see or comment on a JSR by address-
ing comments to the expert group responsible for the JSR. This phase ends during
an approval ballot conducted among members of the JCP; if a document does not
pass the approval ballot, the expert group may submit a revised version that
addresses the community's concerns. Once a JSR has passed the public review
stage, it's likely to undergo little change in the future, except for maintenance.
3.
Maintenance
: Once a JSR is accepted by the community, the expert group provid-
ing the JSR may make minor changes to it to address items that need correction.
4.
Dormancy
: A JSR that no longer has an expert group behind it is said to be dor-
mant. It's likely that dormant JSRs describe APIs that do not have widespread
support among the community, or APIs that have been clearly superseded by
newer initiatives.
Understanding where a JSR is in its life cycle can help you determine whether or
not you can depend on the APIs it provides in your product planning. For example,
basing a product on an API described in a JSR in the early draft phase may be danger-
ous. Before basing a product on a dormant JSR, it's a good idea to understand why that
JSR is dormant.
Over time, I've come up with an approach that enables me to learn and work with
the information in a JSR fairly quickly. The trick is to not only look at the APIs, but also to
try to gain some domain experience about the problem the API designers are trying to
solve. For example, when looking at the SATSA-CRYPTO API in JSR 177, I spent some time
looking at the various technologies in the smart-card industry, even though the project I
was working on wasn't likely to use a specific vendor. I also spent some time looking at
other APIs that other communities have developed that meet the same objective; seeing
how different people approach the same problem of abstracting access to a resource can
shed light on the decisions made for the implementation that the JSR actually docu-
ments. Always keep in mind that at some level, the APIs a JSR defines are really just an
abstraction of some physical system; it's easy to get so wrapped up in the class and object
model that you forget the real-world underpinnings.
