Bug 49634 - Modularity of freeform project type
Modularity of freeform project type
Status: RESOLVED FIXED
Product: projects
Classification: Unclassified
Component: Ant
4.x
All All
: P1 (vote)
: 4.x
Assigned To: David Konecny
issues@projects
buildsys-e-cand
: API, API_REVIEW_FAST, ARCH
Depends on: 49647 51151
Blocks: 42682 49756
  Show dependency treegraph
 
Reported: 2004-09-28 16:27 UTC by Jesse Glick
Modified: 2004-12-08 09:50 UTC (History)
4 users (show)

See Also:
Issue Type: ENHANCEMENT
:


Attachments
zipped FreeformProjectSPI Javadoc (88.92 KB, application/octet-stream)
2004-11-30 16:20 UTC, David Konecny
Details
zipped JavaFreeformProjectSPI Javadoc (48.19 KB, application/octet-stream)
2004-11-30 16:20 UTC, David Konecny
Details
arch answers html file for web/freeform (48.94 KB, text/html)
2004-11-30 16:25 UTC, David Konecny
Details
diff of changes based on Yarda's suggestions (17.08 KB, patch)
2004-12-02 18:16 UTC, David Konecny
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Jesse Glick 2004-09-28 16:27:18 UTC
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.
Comment 1 Jesse Glick 2004-10-07 13:24:22 UTC
Seems it will be needed for E.
Comment 2 Jan Chalupa 2004-11-09 08:23:02 UTC
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
feasible?
Comment 3 Jesse Glick 2004-11-09 23:31:52 UTC
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.
Comment 4 David Konecny 2004-11-10 10:25:15 UTC
OK, I'm going to look at that and prepare some answers.
Comment 5 David Konecny 2004-11-30 16:20:03 UTC
Created attachment 19086 [details]
zipped FreeformProjectSPI Javadoc
Comment 6 David Konecny 2004-11-30 16:20:30 UTC
Created attachment 19087 [details]
zipped JavaFreeformProjectSPI Javadoc
Comment 7 David Konecny 2004-11-30 16:25:03 UTC
Created attachment 19088 [details]
arch answers html file for web/freeform
Comment 8 David Konecny 2004-11-30 16:33:00 UTC
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
by j2ee/freeform.

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.ant.freeform.spi.support and
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.
Comment 9 Jaroslav Tulach 2004-12-02 08:30:53 UTC
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
activated?

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?

document: use
url="@TOP@/org/netbeans/modules/ant/freeform/spi/ProjectNature.html"
in api definition of ProjectNature api (at least I hope it works)



Comment 10 David Konecny 2004-12-02 14:28:52 UTC
Thanks.

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
ProjetcNature.getExtraTargets().

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.
Comment 11 Jesse Glick 2004-12-02 16:26:15 UTC
David make sure to include all these explanations in the arch.xml (or
Javadoc), not just write them here...
Comment 12 David Konecny 2004-12-02 18:16:42 UTC
Created attachment 19110 [details]
diff of changes based on Yarda's suggestions
Comment 13 David Konecny 2004-12-02 18:18:01 UTC
Yarda, I just attached diff which I hope impl your comments. Feel free
to further comment. Thanks.
Comment 14 Jaroslav Tulach 2004-12-03 09:00:41 UTC
Thanks, I think this is good enough for friend api with one additional
suggestion:

As you may know the "arch-usecases" section is displayed at
http://www.netbeans.org/download/dev/javadoc/usecases.html
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.

Comment 15 Jesse Glick 2004-12-03 16:30:23 UTC
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
you think?
Comment 16 Jaroslav Tulach 2004-12-06 11:26:16 UTC
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.
Comment 17 Pavel Buzek 2004-12-06 14:45:13 UTC
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
this case.

http://openide.netbeans.org/tutorial/api-design.html#life
Comment 18 David Konecny 2004-12-07 09:05:32 UTC
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.
Comment 19 David Konecny 2004-12-07 14:29:41 UTC
Integrated to trunk.
Comment 20 David Konecny 2004-12-08 09:50:16 UTC
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.


By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2014, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo