Folks,
although I follow the list pretty close, I've not done much practical
programming with qi4j yet, except for stepping through the tutorial
code. So I tried to start with my own example.
After defining my (entity) composites I tried to assemble the parts, to
be ready for take off. So I followed the HowTo mentioned in the subject.
But it didn't work because e.g. the Energy4Java#newApplicationAssembly()
used in the sample code does (no longer) exist.
While I could have looked at the testcases in the codebase at this point
to figure out what needs to be done, I didn't do that.
Instead I thought about what could be done to eliminate this drawback.
I think the inconsistency stems from the fact, that the codebase is
still in a state of flux (which is good at this time) and that the code
snippets used as example code are not tied to the codebase (which is not
so good). The glue between the codebase and the sample snippets is
manual work. And that gets easily forgotten when performing a refactoring.
There are many options to solve the inconsistency, e.g.
1. don't care about => some people will become frustrated
2. tie the sample code to a release and state that explicitly => sample
will work always; there is still manual work when migrating the sample
to a newer release; migration tends to be forgotten, samples 'erode'
3. remove all sample code => also not very attractive
4. literate programming => overkill (ok, was a joke)
5. reference code snippets from the (current) codebase in the samples =>
samples are always compileable; with appropriate testcases, chances are
high that the code will even run most of the time; sample code is
refactoring safe
6. ... and perhaps many more ...
To be honest, I first thought about option 5., so I took javacc and the
bundled Java 1.5 grammer and tweaked it a bit, so that special single
line comments can be used for marking code snippets as such.
I came up with the syntax below, where the snippet named 'main' is defined:
public class Sample
{
// $$Snippet(main)$$
public static void main( String[] args )
{
for( String string : args )
{
System.out.println();
}
}
// $$Snippet$$
}
Retrieving the snippet(s) is nothing more than:
@Test
public void testHtmlDecorator()
throws MalformedURLException,
IOException,
ParseException
{
JSnippyParser jsp = new JSnippyParser();
List<PlainSnippet> ss = jsp.parse( new File( fileName
).toURI().toURL() );
for( PlainSnippet snippet : ss )
{
HtmlDecorator hsn = new HtmlDecorator( snippet );
System.out.println( hsn.format( false, true ) );
}
}
1. create the parser
2. parse a java source given as java.net.URL
3. iterate over the list of snippets and do what you want
4. e.g. decorate it with html
So to come back to the 'sample code not in sync with codebase' problem:
One could wrap this functionality with a servlet (or e.g. a
SiteVison-Plugin or whatever is possible), to create the notion of a
snippet-url like e.g.
http://www.qi4j.org/snippets/samples/helloworld/src/main/java/org/qi4j/samples/hello/composite/CustomHelloWorldComposite.java/snippet_name
which maps to snippet named 'snippet_name' in
https://scm.ops4j.org/repos/ops4j/projects/qi4j/samples/helloworld/src/main/java/org/qi4j/samples/hello/composite/CustomHelloWorldComposite.java
Then the snippet-url could be used with an iframe in the sample text (or
whatever mechanism SiteVision supports).
Possible? Reasonable? Or just a 'middle of the night scrap'?
WDYT?
Cheers
Georg
_______________________________________________
qi4j-dev mailing list
[email protected]
http://lists.ops4j.org/mailman/listinfo/qi4j-dev
