commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Morgan Delagrange <mdela...@yahoo.com>
Subject Re: [Jelly] Release Issue 2 - Jelly public API
Date Tue, 07 Jan 2003 18:26:30 GMT

--- James Strachan <james_strachan@yahoo.co.uk> wrote:
> From: "Morgan Delagrange" <mdelagra@yahoo.com>
> > 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.

I actually moved the task package into the Ant taglib,
which allowed us to remove our dependencies on ant,
ant-optional, and grant.  I think it's a good move,
but I might be wrong.

> 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?

Splitting them up might be a good idea.  It would be
great if we can say "use this package" and "don't use
that package".

> 
> 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

Some tags might be conducive to extension, but I'm not
sure a tag chosen at random would be suitable for it. 
Tags can be very sensitive to parents, children,
Context variables, etc. in ways that are not obvious
at the method level.  You know what I mean?

> > 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?

Not really.

- Morgan

> 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:commons-dev-unsubscribe@jakarta.apache.org>
> For additional commands, e-mail:
> <mailto:commons-dev-help@jakarta.apache.org>
> 


=====
Morgan Delagrange
http://jakarta.apache.org/taglibs
http://jakarta.apache.org/commons
http://axion.tigris.org
http://jakarta.apache.org/watchdog

__________________________________________________
Do you Yahoo!?
Yahoo! Mail Plus - Powerful. Affordable. Sign up now.
http://mailplus.yahoo.com

--
To unsubscribe, e-mail:   <mailto:commons-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@jakarta.apache.org>


Mime
View raw message