Update of /cvsroot/xdoclet/xdoclet2/core/aptdocs
In directory sc8-pr-cvs1:/tmp/cvs-serv478/core/aptdocs
Modified Files:
tags.apt
Added Files:
query-language.apt
Log Message:
-Added a proposal for a simple tag query language
-Updated tag design proposal with some words about a TagMetaData API.
--- NEW FILE: query-language.apt ---
----------------------
Query Language
----------------------
Aslak Hellesoy
----------------------
8 February 2003
----------------------
Query Language
xjavadoc is based on Collection and uses commons-collections' Predicate interface
to filter various Collections. xjavadoc/xdoclet2 has some basic implementations
of the Predicate interface. There are basic logical operators such as And, Or and Not,
but also Predicates that evaluate an xjavadoc API object, such as HasTag, IsA, etc.
Most methods in the xjavadoc API that return a Collection can also take as input
a Predicate argument. Example:
+-----------------------------------------------------------
/**
* @return a Collection of XMethod that have a @foo.bar tag.
*/
public Collection getFooBarMethods(XClass clazz) {
HasTag hasTag = new HasTag();
hasTag.setTagName("foo.bar");
Collection methods = clazz.getMethods();
}
+-----------------------------------------------------------
This is very convenient to express in Java code. You could access this functionality
from Velocity too:
+-----------------------------------------------------------
#foreach( $methods in $myutil.getFooBarMethods($class) )
do something with the method here.
#end
+-----------------------------------------------------------
This reminds us of the XDoclet 1 tag handlers. You code some logic in the java class,
and
you access it from the template. The only difference now is that XDoclet 2's "tag
handlers"
do not perform looping and branching logic, since Velocity/Jelly has that built-in.
Instead, these
XDoclet 2 "tag handlers" would return Collections (for looping), booleans (for
conditionals)
or Strings (for content).
This approach is nice in some scenarios, especially when you want to share the logic
in
these java classes among many templates. We'll definitely need it.
However, it would be nice to have an optional approach too. Imagine if all you had to
write was this:
+-----------------------------------------------------------
#foreach( $method in $class.getMethods("select method where
method.doc.tag.name='foo.bar'") )
do something with the method here.
#end
+-----------------------------------------------------------
And no need to write a separate java class or getFooBarMethods class. A query
language!
This would make it even easier to write plugins for XDoclet.
Of course, this means you're mixing logic and presentation in the same file, and
violates
anything MVC has taught us. But XDoclet plugin writers often want to get a job done
as easily
as possible, and having a simple, albeit a bit dirty, way to prototype templates like
this
would be an enormous achievement.
Implementation
We'd have to define a grammar for the query language and generate a parser for it
with JavaCC, ANTLR
or something else. I suggest we look at Hibernate and see how they have implemented
their query
parser. After all, the grammar will be quite similar. SQLish. -And very simple.
Maybe we don't need any fancy parser either, just use introspection in the same way
as velocity does.
When we have a parser that understands query expressions, we'd have something that
could generate
Predicate objects on the fly, and from there it's business as usual.
Index: tags.apt
===================================================================
RCS file: /cvsroot/xdoclet/xdoclet2/core/aptdocs/tags.apt,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -r1.5 -r1.6
*** tags.apt 11 Feb 2003 11:12:47 -0000 1.5
--- tags.apt 18 Feb 2003 00:57:46 -0000 1.6
***************
*** 153,171 ****
+-------------------------------------------------------------------
! Why not keep the xtags.xml format?
!
! There are several reasons for this. The most obvious reason is that it's too hard
to maintain.
! We'd have to maintain the name of the tag and its attributes in that file, but also
in the
! Generator classes and/or the Velocity templates that will access the tags. This
quickly comes
! out of sync.
!
! The docs will document both tags, and the docs for the deprecated tags will inform
that they
! are deprecated and point to the tag to use.
!
! Further, the validation logic could issue warnings if a deprecated tag is used, but
it would still
! work.
!
! This can be applied both on the tag level and the tag attribute level.
How are the tags instantiated?
--- 153,173 ----
+-------------------------------------------------------------------
! TagMetaData API
+ XJavadoc will be augmented with an API to access meta-data about various @tags.
+This API
+ will provide information about where a tag is appliccable, valid tag attributes,
+whether
+ they are mandatory, description and so on.
+
+ Each @tag will have a separate XML descriptor similar to the current xtags.xml. For
+a tag
+ named @foo.bar, there will be a foo.bar.tag.xml descriptor.
+
+ The TagMetaData API implementation will parse these descriptors and make the
+information
+ available via first-class java objects. This is very useful for IDE plugins that
+want to
+ implement code-completion for @tags.
+
+ The XDoclet plugin developer can choose whether she wants to write the *.tag.xml
+descriptor
+ by hand or have it generated from a tagged DefaultXTag subclass. The XDoclet SDK
+will provide
+ a special XDoclet plugin generate these files.
+
How are the tags instantiated?
-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
_______________________________________________
xdoclet-devel mailing list
[EMAIL PROTECTED]
https://lists.sourceforge.net/lists/listinfo/xdoclet-devel
