Currently the freeform project type is implemented
as a single module, though domain-specific
metadata is split into three schemas: general,
Java-specific, and web-specific. Would like to
introduce SPIs to permit the domain-specific
functionality to be factored into physically
distinct modules that could be independently
maintained. Would also perhaps permit full J2EE
support to add its own hooks.
Precise design TBD - modules should be able to add
to lookup, maybe merge into lookup items? Should
be able to add to list of supported schemas.
Should be able to add panels to properties dialog.
Seems it will be needed for E.
Seems it will be needed soon. The Web Apps team has a dependency and
their tentative plan expects it to be done by end of November. Is it
We talked about it last week and I agreed we needed to begin work on
this immediately - David I will want to talk with you next week on how
ProjectModel etc. should be modularized.
OK, I'm going to look at that and prepare some answers.
Created attachment 19086 [details]
zipped FreeformProjectSPI Javadoc
Created attachment 19087 [details]
zipped JavaFreeformProjectSPI Javadoc
Created attachment 19088 [details]
arch answers html file for web/freeform
I would like to ask for review of newly introduced SPI which I created
as part of freeform module split. Originally monolithic freeform
module was split into domain specific ones which now implement the SPI
in order to plug itself into the base freeform project type.
This issue already went through the DevRev and that's why I'm
submitting this as fast-track although the SPI is not trivial. The
planned stability of SPI is "friend" and it is expected that SPI will
be implemented/used only by java/freeform, web/freeform and soon also
Attached to this issue you can find #1) generated Javadoc of
ant/freeform module with updated arch answers, #2) generated Javadoc
of java/freeform module with updated arch answers and finally #3)
updated arch answers of web/freeform which does not have any public SPI.
From API point of view the most important is only one package:
org.netbeans.modules.ant.freeform.spi. There exist also
org.netbeans.modules.java.freeform.spi.support which both contain
mostly support methods for wizard creation which are not very
impressive, but it is just optional support which may or may not be
used by the modules.
Let me know if you have any questions or recommendations. Thanks.
Advice: Should not other project apis be referenced as official? As
they are going to be official for promoe.
imho request: In the arch-usecases describe how the API can be used.
The architecture schetch just seems to describe overall arch, but not
direct the usecases for module writers. I would like to see an
explanation why the xsd is exported and what I can do with it as well
as explanation of interface in lookup. Uses and especially flow of
calls to methods in NewFreeformProjectSupport could be explained. What
is TargetDescriptor for? How do you find out which Natures should be
document: "Project type is registered in META-INF/services." is an
imported lookup API from a certain module. api tag should imho be used
and it should be verified that the other module really exposes this api.
question: what is the files structure, what files are generated, what
is stability of their location and format? E.g. can user rely on that,
edit them, etc?
in api definition of ProjectNature api (at least I hope it works)
Re. "Advice:" - can be done.
Re. "why the xsd is exported" - users can and are encouraged to modify
project.xml by hand. And (versioned) XML schema defines the format.
Re. "ProjectNature interface in lookup" + "which Natures should be
activated" - will improve its Javadoc. The base project queries all
natures installed in the IDE and asks them whether they want to
enhance the project or not. It's up to the nature to decide that, i.e.
they can read project.xml and check presence of their namespaced metadata.
Re. "flow of calls to methods in NewFreeformProjectSupport" - will
improve its Javadoc. In practice you will not be woried about this
because you are implementing wizard and you know that you need panels,
then you need to instantiate them and then you have to clean them up.
All what NFPS contains are exactly these methods.
Re. "What is TargetDescriptor for" - will link its Javadoc to
Re. two "document:" - will fix that.
Re. "files structure" - will mention project structure - i.e. the
project.xml file always under nbproject directory whose structure is
described by XML schemas which (as already said) are versioned.
David make sure to include all these explanations in the arch.xml (or
Javadoc), not just write them here...
Created attachment 19110 [details]
diff of changes based on Yarda's suggestions
Yarda, I just attached diff which I hope impl your comments. Feel free
to further comment. Thanks.
Thanks, I think this is good enough for friend api with one additional
As you may know the "arch-usecases" section is displayed at
and is base for unofficial (but we do not have any other) NetBeans
faqs. In order to be really useful, please not only enumerate possible
usecases, but also describe how to achieve them. One sentence with a
url to the javadoc is enough I guess.
Since this is a friend SPI, IMHO details of how to achieve usecases
are best described by the source code of the known actual users of the
SPI, in java/freeform and web/freeform. If we were trying to make a
general-purpose public SPI, it would make more sense to describe
hypothetical usecases for interesting portions of the SPI and show
code snippets, but here that just seems completely redundant. What do
There is a bit of truth in your reasoning. Would it be possible to add
at least links to WebCVS of the files that implemenent each usecase?
That should be easy to do and would serve well for future references.
I think the stability level should not be Friend, it should be Under
Development. It will be used in another cluster. Friend API implies
that API will be used by the same group of people that provides the
API. Frient API also implies that "the author of this API does not
have the intent to create a general purpose API" which is not good for
an API used by multiple modules in multiple clusters. I am not saying
the API needs to be stabilizes immediately (maybe no even in the next
release?) but the general goal should be to create a stable API in
Re. usecases: I will add links to SPI impls.
Re. Friend API also implies that "the author of this API does not have
the intent to create a general purpose API": but this is exactly what
these APIs are about. They are not general purpose APIs in the sense
that anybody should/could use them. They are more about private-like
communication in between limited number of well known modules.
Speaking more technically, without regard of crossing cluster
boundaries we would like to mark these APIs as evolving and designed
for limited number of known clients; nobody should use them without
letting us know; there is high probability that APIs may change in
future and known clients will be fixed. They may become stable in
future but at the moment it is not goal/requirement.
Anyway, I guess this is not show stopper so I'm going to merge impl to
trunk and we can alter stability later.
Integrated to trunk.
Sorry for removing the keyword. I reread Review Steps again and now I
see that instead of removing it I should add reviews@ to CC. Done too.