You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@hivemind.apache.org by Knut Wannheden <kn...@gmail.com> on 2004/10/13 13:35:52 UTC
generating hivedoc from parsed descriptors
I've started implementing a HiveDoc generator which gets its input
from ModuleDescriptorProviders instead of reading the XML module
descriptors. This should allow HiveDoc being generated for module
descriptors defined in other formats.
The strategy of the implementation is to assemble a single XML
document equivalent to that which the <createregistry> task creates
and then feed it to the existing XSLT to generate the HiveDoc. Maybe
this strategy should be changed in the future, but for now I think it
should be the easiest approach.
This implementation requires many of the Descriptor classes to be
extended. Most obvious is a new "description" field. There are also a
few cases where the Descriptor classes don't provide a getter. All
this should be easy to fix.
More problematic is:
- <schema>s are not added to the Descriptor defining them. Instead
they're directly linked to the elements using them. But this leaves
out any unused schemas (e.g. "hivemind.lib.Pipeline").
- A <conversion> element is "unwrapped" and cannot be distinguished
from its <rules> equivalent.
Anyone got thoughts on this?
--knut
---------------------------------------------------------------------
To unsubscribe, e-mail: hivemind-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-dev-help@jakarta.apache.org
Re: generating hivedoc from parsed descriptors
Posted by Knut Wannheden <kn...@gmail.com>.
Another thing we need to look into is how a user is supposed to
generate HiveDoc for custom ModuleDescriptorProviders. It would of
course be nice if this were possible with an Ant task. But how should
the providers be specified by the user and then later initialized by
the task? Requiring a no-arg constructor and no further
initialization is not very satisfying...
The best idea I can come up with is to provide a HiveMind service for
the HiveDoc generation. The user would have to specify the custom
providers as contributions to a defined configuration point. (Of
course he can then define the custom providers as services with their
own configurations.) In the Ant file it would only be a matter of
specifying the path to the module descriptors with the contributions.
Now these descriptors have to be in the default XML format! Otherwise
the user is more than welcome to write his own HiveDoc generator :-)
Anyone got a better idea?
--knut
---------------------------------------------------------------------
To unsubscribe, e-mail: hivemind-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-dev-help@jakarta.apache.org
Re: generating hivedoc from parsed descriptors
Posted by Knut Wannheden <kn...@gmail.com>.
Hi again,
As a general purpose DescriptorVisitor I'd imagined something like
Eclipse's hierarchical ASTVisitor:
public abstract class Descriptor {
public boolean visit(ModuleDescriptor md) {
return true;
}
public boolean visit(ServicePointDescriptor spd) {
return true;
}
...
public void endVisit(ServicePointDescriptor spd) {
}
public void endVisit(ModuleDescriptor md) {
}
}
The boolean returned by the visit() methods would signify whether the
children of the visited descriptor should be visited or not. The
Descriptor classes would have an accept(DescriptorVisitor) method
which implements the visiting of the children. E.g.
public class ModuleDescriptor {
public void accept(DescriptorVisitor visitor) {
boolean visitChildren = visitor.visit(this);
if (visitChildren && _servicePoints != null)
// _servicePoints.each { sp | sp.accept(visitor); }
visitor.endVisit(this);
}
}
Implementing a visitor is then simply a matter of extending
DescriptorVisitor and overload the respective methods required.
Is this overkill? Other ideas?
--knut
On Thu, 14 Oct 2004 16:45:55 +0200, Knut Wannheden
<kn...@gmail.com> wrote:
> Hi all,
>
> I've committed the changes to CVS now. As I said it should be regarded
> as a first (but yet feature complete) implementation of the new
> HiveDoc generator. I see the following things needing refactoring:
>
> - Schema objects should be added to the Descriptors in which they were
> defined. Descriptors referencing schemas defined elsewhere should only
> have a String id thereof. This will delegate the schema linking
> responsibility to the RegistryBuilder, which IMO makes more sense.
> This should further allow us to remove the dependency on
> RegistryAssembly in DescriptorParser.
> - There should be a switch on the DescriptorParser to control whether
> annotations should be parsed or not. The client of
> XmlModuleDescriptorParser obviously needs to be in control of this
> switch.
> - Howard's suggested XMLWriter and visiting pattern for the Descriptor
> classes should be considered. Alternatively a more general purpose
> visitor class could be implemented. It would also be useful to the
> RegistryBuilder.
>
> That's all I've written down anyway ;-)
>
> Support for scripts (e.g. Groovy) should be within reach now.
>
> --knut
>
---------------------------------------------------------------------
To unsubscribe, e-mail: hivemind-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-dev-help@jakarta.apache.org
Re: generating hivedoc from parsed descriptors
Posted by Knut Wannheden <kn...@gmail.com>.
Hi all,
I've committed the changes to CVS now. As I said it should be regarded
as a first (but yet feature complete) implementation of the new
HiveDoc generator. I see the following things needing refactoring:
- Schema objects should be added to the Descriptors in which they were
defined. Descriptors referencing schemas defined elsewhere should only
have a String id thereof. This will delegate the schema linking
responsibility to the RegistryBuilder, which IMO makes more sense.
This should further allow us to remove the dependency on
RegistryAssembly in DescriptorParser.
- There should be a switch on the DescriptorParser to control whether
annotations should be parsed or not. The client of
XmlModuleDescriptorParser obviously needs to be in control of this
switch.
- Howard's suggested XMLWriter and visiting pattern for the Descriptor
classes should be considered. Alternatively a more general purpose
visitor class could be implemented. It would also be useful to the
RegistryBuilder.
That's all I've written down anyway ;-)
Support for scripts (e.g. Groovy) should be within reach now.
--knut
---------------------------------------------------------------------
To unsubscribe, e-mail: hivemind-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-dev-help@jakarta.apache.org
Re: generating hivedoc from parsed descriptors
Posted by Knut Wannheden <kn...@gmail.com>.
On Wed, 13 Oct 2004 11:33:14 -0400, Howard Lewis Ship <hl...@gmail.com> wrote:
> I had been thinking in terms of an XMLWriter interface (similar to
> Tapestry's IMarkupWriter). This would allow easy XML output with
> methods like begin(), attribute(), write() and end().
>
> A second interface, XMLWritable, woudl be implemented by the various
> descriptor objects, i.e.
>
> public void writeXML(XMLWriter writer);
>
Or how about a more general purpose DescriptorVisitor interface and
corresponding visit(DescriptorVisitor) methods on the Descriptor
classes? This visitor could then also be used by the RegistryBuilder.
> What's your solution shaping up as?
>
The approach I had in mind was to begin with implementing an
alternative <constructregistry> task. This task would get the
ModuleDescriptors from the default XmlModuleDescriptorProvider and
build up the XML document by traversing the Descriptor tree.
> On Wed, 13 Oct 2004 16:26:42 +0200, Knut Wannheden
> <kn...@gmail.com> wrote:
> > Update. I've now implemented the HiveDoc generator as described in
> > the previous message. The limitations are still:
> >
> > - not all schemas are generated into HiveDoc
> > - <conversion>s are displayed as their <rules> equivalent
> >
> > The second limitation can probably be addressed by inversing the
> > dependency between ConversionDescriptor and ElementModelImpl...
> > somehow :-)
>
> Shouldn't be too hard to create a ConversionDescriptor or somesuch.
>
I have now solved this by letting ConversionDescriptor implement the
Rule interface. The calls to begin() and end() just delegate to the
CreateObjectRule, ReadAttributeRules, and InvokeParentRule. The twist
is just that the <conversion> is not really a rule (it's not nested in
<rules>), but the purpose of the two is a common denominator. It's
just the term that's missing.
Currently the implementation just doesn't generate HiveDoc for
unreferenced schemas yet, otherwise it is feature complete. Once I
have solved that I'd like to commit the implementation as a first
iteration to CVS. Then we can take a look at the refactorings we've
discussed. Sounds good?
--knut
---------------------------------------------------------------------
To unsubscribe, e-mail: hivemind-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-dev-help@jakarta.apache.org
Re: generating hivedoc from parsed descriptors
Posted by Howard Lewis Ship <hl...@gmail.com>.
Sounds to me like you are on the right track!
Possibly there should be a switch on ModuleDescriptorParser to have it
ignore descriptions except when parsing for HiveDoc.
I had been thinking in terms of an XMLWriter interface (similar to
Tapestry's IMarkupWriter). This would allow easy XML output with
methods like begin(), attribute(), write() and end().
A second interface, XMLWritable, woudl be implemented by the various
descriptor objects, i.e.
public void writeXML(XMLWriter writer);
What's your solution shaping up as?
On Wed, 13 Oct 2004 16:26:42 +0200, Knut Wannheden
<kn...@gmail.com> wrote:
> Update. I've now implemented the HiveDoc generator as described in
> the previous message. The limitations are still:
>
> - not all schemas are generated into HiveDoc
> - <conversion>s are displayed as their <rules> equivalent
>
> The first limitation could be solved by simply adding a getter to the
> RegistryAssembly. However, I think it might be cleaner if the
> Descriptor objects would retain the distinction between defining a
> schema and referencing an existing schema. I.e. the
> ConfigurationPointDescriptor could be changed from:
>
> public Schema getContributionsSchema();
> public void setContributionsSchema(Schema schema);
>
> to:
>
> public Schema getSchema();
> public void setSchema(Schema schema);
> public String getSchemaId();
> public void setSchemaId(String schemaId);
This can also affect ServicePointDescriptor (parameters schema).
>
> That's making the Descriptor classes more complex. But on the positive
> side I think it should then be possible to remove the dependency on
> RegistryAssembly in DescriptorParser (and thus also in
> ModuleDescriptorProvider). The RegistryAssembly is only used to
> resolve schema references (using SchemaInjector), which wouldn't be
> needed anymore. Thoughts on this?
>
> The second limitation can probably be addressed by inversing the
> dependency between ConversionDescriptor and ElementModelImpl...
> somehow :-)
Shouldn't be too hard to create a ConversionDescriptor or somesuch.
I wrote it the way I did to limit the amount of new code I needed to
test. Requirements change; here there's a requirement to allow
reproducability to XML.
>
> --knut
>
> On Wed, 13 Oct 2004 13:35:52 +0200, Knut Wannheden
>
>
> <kn...@gmail.com> wrote:
> > I've started implementing a HiveDoc generator which gets its input
> > from ModuleDescriptorProviders instead of reading the XML module
> > descriptors. This should allow HiveDoc being generated for module
> > descriptors defined in other formats.
> >
> > The strategy of the implementation is to assemble a single XML
> > document equivalent to that which the <createregistry> task creates
> > and then feed it to the existing XSLT to generate the HiveDoc. Maybe
> > this strategy should be changed in the future, but for now I think it
> > should be the easiest approach.
> >
> > This implementation requires many of the Descriptor classes to be
> > extended. Most obvious is a new "description" field. There are also a
> > few cases where the Descriptor classes don't provide a getter. All
> > this should be easy to fix.
> >
> > More problematic is:
> >
> > - <schema>s are not added to the Descriptor defining them. Instead
> > they're directly linked to the elements using them. But this leaves
> > out any unused schemas (e.g. "hivemind.lib.Pipeline").
> > - A <conversion> element is "unwrapped" and cannot be distinguished
> > from its <rules> equivalent.
> >
> > Anyone got thoughts on this?
> >
> > --knut
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: hivemind-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: hivemind-dev-help@jakarta.apache.org
>
>
--
Howard M. Lewis Ship
Independent J2EE / Open-Source Java Consultant
Creator, Jakarta Tapestry
Creator, Jakarta HiveMind
http://howardlewisship.com
---------------------------------------------------------------------
To unsubscribe, e-mail: hivemind-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-dev-help@jakarta.apache.org
Re: generating hivedoc from parsed descriptors
Posted by Knut Wannheden <kn...@gmail.com>.
Update. I've now implemented the HiveDoc generator as described in
the previous message. The limitations are still:
- not all schemas are generated into HiveDoc
- <conversion>s are displayed as their <rules> equivalent
The first limitation could be solved by simply adding a getter to the
RegistryAssembly. However, I think it might be cleaner if the
Descriptor objects would retain the distinction between defining a
schema and referencing an existing schema. I.e. the
ConfigurationPointDescriptor could be changed from:
public Schema getContributionsSchema();
public void setContributionsSchema(Schema schema);
to:
public Schema getSchema();
public void setSchema(Schema schema);
public String getSchemaId();
public void setSchemaId(String schemaId);
That's making the Descriptor classes more complex. But on the positive
side I think it should then be possible to remove the dependency on
RegistryAssembly in DescriptorParser (and thus also in
ModuleDescriptorProvider). The RegistryAssembly is only used to
resolve schema references (using SchemaInjector), which wouldn't be
needed anymore. Thoughts on this?
The second limitation can probably be addressed by inversing the
dependency between ConversionDescriptor and ElementModelImpl...
somehow :-)
--knut
On Wed, 13 Oct 2004 13:35:52 +0200, Knut Wannheden
<kn...@gmail.com> wrote:
> I've started implementing a HiveDoc generator which gets its input
> from ModuleDescriptorProviders instead of reading the XML module
> descriptors. This should allow HiveDoc being generated for module
> descriptors defined in other formats.
>
> The strategy of the implementation is to assemble a single XML
> document equivalent to that which the <createregistry> task creates
> and then feed it to the existing XSLT to generate the HiveDoc. Maybe
> this strategy should be changed in the future, but for now I think it
> should be the easiest approach.
>
> This implementation requires many of the Descriptor classes to be
> extended. Most obvious is a new "description" field. There are also a
> few cases where the Descriptor classes don't provide a getter. All
> this should be easy to fix.
>
> More problematic is:
>
> - <schema>s are not added to the Descriptor defining them. Instead
> they're directly linked to the elements using them. But this leaves
> out any unused schemas (e.g. "hivemind.lib.Pipeline").
> - A <conversion> element is "unwrapped" and cannot be distinguished
> from its <rules> equivalent.
>
> Anyone got thoughts on this?
>
> --knut
>
---------------------------------------------------------------------
To unsubscribe, e-mail: hivemind-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: hivemind-dev-help@jakarta.apache.org