A paragraph describing the basic purpose of the presented sample. In
general, the purpose of a sample could be, but not limited to,
to highlight some new feature introduced in a release (e.g. Bean
Validation or Criteria API)
to describe wiring between frameworks e.g. JSF and JPA, GWT and JPA
to demonstrate operation within a container e.g. OSGi, Spring, Tomcat
a combination of the above
"this sample demonstrates usage of new Bean Validation API in a
multi-tier web application"
or "this sample integrates client-side Google Web Toolkit architecture with
sever-side JPA application".
The functional features of the samples such as "This OpenBooks example
can be used to place order and browse books" -- are not that important in
this context but can be mentioned.
State the availability of the sample. For example,
Is the distribution available as a downloadable archieve? If packaged
in an archieve, all source code, build instructions must be available in
the distribution itself. A README.txt should be inside and outside the
Is the sample to be checked out from code repository? In such cases,
building the sample should be done with Ant or Maven. Prefer Ant to make
the dependencies and steps more visible.
The steps in this section should be clear and concise for an user to
follow them to build, deploy and run the sample.
Enumerate the software artifacts required to build, deploy and run the
sample. The artifacts should be categorized into build time and run time
Often building a sample will require the user to configure dependencies
(such as OpenJPA libraries or JDBC Driver), for his/her local environment.
The ANT build scripts for a sample must accept configurable properties via
build.properties or similar configurable mechanics. The properties
configuration file itself should be documented to explain the dependencies
and how the build script use them. Maven based build scripts can make these
dependencies more implicit and saves the user to explicitly satisfy such
dependencies. However, ANT based builds are preferred over Maven for the
samples, so that the build steps and dependencies are made more visible to
The samples, besides demonstration of a feature, are a suitable vehicle
of showing good development practices in JPA application programming model
such as persistent domain modeling or architectural practices. It is
recommended that such best practices be mentioned in several places:
in the source code
a separate document that enumerates them in one place.
The complete develop-build-run cycle of a sample will often bring out the
special considerations. For example, reported common errors in deployment
in a container and their remedies or certain undesirable usage patterns.
The description of a sample should highlight these special considerations
rather than making the exercise appear as a series of perfectly easy steps.
The caveats can be further highlighted by linking them to relevant JIRA
issues or forum discussions or external blogs etc.