Hey All,
Figuring out a way to document our examples and get them on the
website has been in the back of my mind for a while. Since I created
that one example yesterday, I felt the pressure to bite that bullet
and finally took a stab at it. Let's see if I can't get some notes
out on it while I still remember all the details. Here goes...
First i created an empty wiki page and added four {snippet} macro
declarations pointing to the files in svn that I wanted to show from
the example. If I were to template that it'd look something like this:
h1. Overview
{snippet:url=openejb3/examples/telephone-stateful/README.txt}
h1. The Code
{snippet:url=openejb3/examples/telephone-stateful/src/main/java/
org/apache/openejb/examples/telephone/TelephoneBean.java|lang=java}
{snippet:url=openejb3/examples/telephone-stateful/src/main/java/
org/apache/openejb/examples/telephone/Telephone.java|lang=java}
{snippet:url=openejb3/examples/telephone-stateful/src/test/java/
org/apache/openejb/examples/telephone/TelephoneTest.java|lang=java}
Then I went through the source and added "tags" for the snippet macro
so I could chop out specific bits for usage in the wiki
documentation. You can do this by adding "START SNIPPET: foo" and
"END SNIPPET: foo" comments in your xml or java or whatever source.
Then you can add an "id" attribute to your {snippet} macros like so:
{snippet:id=foo|url=openejb3/examples/telephone-stateful/src/main/
java/org/apache/openejb/examples/telephone/Telephone.java|lang=java}
Then I went and slowly filled out the details, breaking things into
subsections and adding notes on EJB3 rules, etc. Several cycles of
that till you're satisfied.
So, I was committing like crazy while creating the doc and I'm left
wondering how I would go about this if I didn't have commit. I guess
in that scenario I'd probably get my example working, then I'd go
straight to the wiki and start creating a page for it. I'd forget
about the snippet macro and just copy/paste in the chuncks of code as
you'd typically do. When I was done creating the doc, I'd trim off
the overview and use it to create the README.txt file, then I'd see
what code chucnks I used and tag up all the source so we could
instead use the snippet macro once the code is committed. In short,
create your example, write your doc, then go back snippet-tag your
files and finally submit patch.
Anyway, hopefully we can get a wiki page for our website for each
example we have. We could send notifications to the user list when
done and also start a new section at the top right of our website
just for EJB3 Examples.
Any refinements/improvements welcome. If you end up tacking
documenting an example, feel free to take a fresh (i.e. totally
different) approach. Whatever get the job done :) Try and drop some
notes on the list if you do.
-David
On Dec 28, 2006, at 11:43 PM, David Blevins wrote:
All,
There is a new EJB3 tutorial/example available.
This example shows how to use OpenEJB3's remoting capabilities in
an embedded scenario to invoke an EJB3 Stateful bean local and over
a network.
http://cwiki.apache.org/OPENEJB/embedded-and-remotable.html
It should download and run as-is, you will not need to build
OpenEJB to run this example. You only need a current Maven 2 install.
Comments, questions, criticisms, corrections welcome.
As always, people are welcome to edit the wiki.
-David
