From: "Morgan Delagrange" <[EMAIL PROTECTED]>
> Hey all,
>
> I think it would be a good idea to identify the 1.0
> Jelly API. By API, I mean the "external interface" as
> described in the Commons versioning guidelines
> (http://jakarta.apache.org/commons/versioning.html).
> For many Commons components we have simply defaulted
> to the public and protected methods of all classes.
> In Jelly's case this is not sufficient. Defining a
> more restricted Java API gives us a convenient way to
> describe our core functionality in the documentation,
> plus we can change underlying implementations without
> compatibility issues. Also, we have command line and
> XML elements to our API.
>
> Certainly the API should include the XML syntax of the
> core taglibs (core, ant?, logging?, junit?, util?).
> It should also include the syntax of the command line
> interface. Which classes should be part of the API?
> I think I can safely say that every class in the
> 'jelly' package
>
(http://jakarta.apache.org/commons/sandbox/jelly/apidocs/org/apache/commons/
jelly/package-summary.html)
> is part of the external interface, but every class in
> 'jelly.parser'
>
(http://jakarta.apache.org/commons/sandbox/jelly/apidocs/org/apache/commons/
jelly/parser/package-summary.html)
> is part of the internal interface. I'm also pretty
> sure that all classes in 'jelly.servlet' should be
> public-facing. I'm not sure about the classes in
> 'jelly.expression', 'jelly.expression.jexl',
> 'jelly.impl', and 'jelly.tags'.
Agreed.
The main public API up to now has been in o.a.c.jelly.
There are then 2 optional APIs (so far) that can be used
o.a.c.jelly.servlet - for those using Jelly inside Servlets
o.a.c.jelly.task - for those using Jelly from inside Ant.
For tag implementors the following packages may be useful
o.a.c.jelly.expression - for working with expressions
o.a.c.jelly.impl - core implementation classes for Jelly
Maybe the last package could be refactored into a package of interfaces &
classes which might be useful to tag implementators, and a package of
implementation classes used by the Jelly engine itself? Right now this
package serves a dual role. Though its a pretty small package. But maybe the
interfaces used by tag implementations could move to o.a.c.jelly.tags?
FWIW I've modified the javadoc generation (when using CVS HEAD of Maven) so
that the above groupings of packages is reflected in the javadoc.
> I'm inclined to say that only the XML syntax of tags
> is officially part of the API. Classes in
> 'jelly.tags.*' should be considered an internal
> interface, and modifying/extending those classes
> should be unsupported. I don't believe that we are
> going to spend enough effort on the internals of those
> tag classes to make them suitable for extension.
> Thoughts?
Whilst these tags are implementation details, they can be reused. e.g. the
UseBeanTag from the core library is quite reusable in other libraries. See
the list of known subclasses.
http://jakarta.apache.org/commons/sandbox/jelly/apidocs/org/apache/commons/j
elly/tags/core/UseBeanTag.html
> Also, any ideas on how best to communicate the details
> of the API to the user? I think an explicit section
> in the Jelly documentation is the minimum, but Javadoc
> comments might also be useful.
Agreed. I've added a grouping of the public/private API to the javadoc
generation.
Apart from generating the tag reference...
http://jakarta.apache.org/commons/sandbox/jelly/tags.html
(which will need to be updated now we've split up the build process), I'm
not sure what else we could do on the 'XML syntax of tags' issue. Any other
ideas?
James
-------
http://radio.weblogs.com/0112098/
__________________________________________________
Do You Yahoo!?
Everything you'll ever need on one web page
from News and Sport to Email and Music Charts
http://uk.my.yahoo.com
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
