This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.

Bug 245153

Summary: No way to create a maven archetype without reflection/impl/friend dep
Product: projects Reporter: Jaroslav Tulach <jtulach>
Component: MavenAssignee: Tomas Stupka <tstupka>
Status: RESOLVED FIXED    
Severity: normal CC: apireviews
Priority: P3 Keywords: API_REVIEW_FAST
Version: 8.0.1   
Hardware: PC   
OS: Linux   
Issue Type: DEFECT Exception Reporter:
Attachments: maven archetype module
new patch

Description Jaroslav Tulach 2014-06-20 10:59:49 UTC
I have a module which provides a wizard and at its very end generates and open a Maven project from a Maven archetype. As my module is new (e.g. is not friend) and as it is itself Maven built (e.g. hard to do implementation dependencies) I had to resolve to reflection. See:

http://hg.netbeans.org/html4j/nb/file/5b5666f697a3/demo/wizard/src/main/java/org/netbeans/modules/project/htmljava/ArchetypeCreator.java

There seems to be no reason for keeping the org.netbeans.modules.maven.api.archetype on friend stability. As far as I can tell it is minimalistic, extensible and there are just few deprecations. As such I'd like it to be exposed as a stable API in a separate module.

Once that is released, I rewrite my module to use such API. Thanks.
Comment 1 Tomas Stupka 2014-07-14 13:24:23 UTC
Created attachment 148036 [details]
maven archetype module
Comment 2 Tomas Stupka 2014-07-14 13:29:36 UTC
- moved the archetype friend package into a new module (maven.archetype) and made it public

- tests, arch.xml, apichanges.xml are part of the patch 

- no new classes or methods added to the api
- no changes in the already existing signatures

please review
Comment 3 Milos Kleint 2014-07-14 23:46:47 UTC
MK1: will the existing users of the maven module need to upgrade to the new api module?
that would be incompatible change for maven module, right?
Comment 4 Tomas Stupka 2014-07-15 09:21:22 UTC
(In reply to Milos Kleint from comment #3)
> MK1: will the existing users of the maven module need to upgrade to the new
> api module?
> that would be incompatible change for maven module, right?
yes, the few existing friend users of archetype will have to be changed

did not attach the patch (seemed to be too straight forward), but can do in case the wish appears.
Comment 5 Milos Kleint 2014-07-15 10:07:37 UTC
right, but then apart from official friend there is  bunch of other people using the yenta approach (https://bitbucket.org/jglick/yenta) which is what we have been recommending to people with new/unstable modules for some time (many projects don't even reach maturity to step up to become official a friend). 

<rant>
I recall recommending the same to yarda (not sure if for this specific usecase)  but for religious/philosophical reasons it's apparently not good enough for his pet project and he decided to break everyone else.
</rant>

-1 (no-go) on the api change from me. Do we have anyone else who depends exclusively on archetypes part of the api and doesn't need anything else from the maven modules? So most will still need friend dependency on maven/maven.embedder even after this change. I suspect we don't many/any such modules, so we end up with broken backward compatibility (and potentially multiple broken dependencies) and one module (html4java) that can claim victory, IMHO the price is too high.
Comment 6 Jaroslav Tulach 2014-07-16 07:17:44 UTC
Y01 I don't see the removed parts of the code. But I assume the API signature remains 1:1 with the original API. In such case there should be no breakage for existing clients, right?

Y01a Use module-auto-deps.xml in maven to make sure everyone who depended on the old version of the maven module gets dependency on maven.archetype as well.

Y02 MavenArchetypeProvider could use the "check for only one subclass" pattern in constructor to prevent misuse by 3rd party: if (!getClass().getName().equals("xxx")) throw ISE();

Y02a The API does not work with implementation of the provider right? In such case specify OpenIDE-Module-Needs in manifest to make sure the provider is present.

Y02b I would rename the MavenArchetypeProvider to some nasty name, so API users are not willing to check what it is. "Impl" or "UI" come to my mind.

Y02c Are you sure about module dependencies? Does it really need maven.model or maven.indexer? Some cleanup would be good. 

Y02d If one of maven deps remains, then the MavenArchetypeProvider could even be declared in it and not exposed in the public API at all.
Comment 7 Jaroslav Tulach 2014-07-16 07:46:05 UTC
(In reply to Milos Kleint from comment #5)
> <rant>
> I recall recommending the same to yarda (not sure if for this specific
> usecase)  but for religious/philosophical reasons it's apparently not good
> enough for his pet project and he decided to break everyone else.
> </rant>

Mostly correct. Just the "pet project" is an official NetBeans project and an important base for NetBeans 9 multi screen UI support. As such I am seeking stable solution, but ...

> so we end up with broken backward compatibility

... not at the cost of breaking compatibility. However I believe we can find solution that preserves it. Then we should have best of both: an official API for newcomers, with compatibility to old timers.
Comment 8 Milos Kleint 2014-07-16 07:52:53 UTC
(In reply to Jaroslav Tulach from comment #7)
> (In reply to Milos Kleint from comment #5)
> 
> > so we end up with broken backward compatibility
> 
> ... not at the cost of breaking compatibility. However I believe we can find
> solution that preserves it. Then we should have best of both: an official
> API for newcomers, with compatibility to old timers.

if it's part of netbeans default distro, making it a friend is a no-brainer IMHO.(as you don't even need to support previous versions of netbeans without the friend tag - unlike the external modules that want to support already released versions).

My objection about the general usefulness of the new API stands. Most plugins will require maven/maven.embedder anyway, as most will need at least NbMavenProject access.
Comment 9 Jaroslav Tulach 2014-07-16 11:58:14 UTC
> if it's part of netbeans default distro, making it a friend is a no-brainer
> IMHO.

I am not a friend of intercluster friend dependencies. Moreover I'd like to have the API now, for 8.0.1, and for this release my module will continue to remain on plugin portal.

> My objection about the general usefulness of the new API stands. Most
> plugins will require maven/maven.embedder anyway, as most will need at least
> NbMavenProject access.

Modules that encapsulate Maven archetype with a new project wizard are fine with the currently proposed API. Being able to write nice wizards over selected archetypes is a good usecase, as far as I can tell.

Should we discover a need for more APIs, we should follow the same path: extract that API into a module which we can declare as stable and offer everyone to use. That is however out of the scope of this API change request.
Comment 10 Tomas Stupka 2014-07-16 16:53:57 UTC
> Y02c Are you sure about module dependencies? Does it really need maven.model or maven.indexer? Some cleanup would be good. 
yes, i'm sure.

One more thing worth mentioning at this place is that o.n.m.maven.archetype.api.Archetype has some o.apache.maven types in it's signatures. Any suggestions?

> Y01 I don't see the removed parts of the code. But I assume the API signature remains 1:1 with the original API. In such case there should be no breakage for existing clients, right?
signature remained 1:1 just for one depraceted method
public static WizardDescriptor.InstantiatingIterator<?> definedArchetype() ...

> Y01a Use module-auto-deps.xml in maven to make sure everyone who depended on the old version of the maven module gets dependency on maven.archetype as well.
done

> Y02 MavenArchetypeProvider could use the "check for only one subclass" pattern in constructor to prevent misuse by 3rd party: if (!getClass().getName().equals("xxx")) throw ISE();
done

> Y02a The API does not work with implementation of the provider right? In such case specify OpenIDE-Module-Needs in manifest to make sure the provider is present.
done

> Y02b I would rename the MavenArchetypeProvider to some nasty name, so API users are not willing to check what it is. "Impl" or "UI" come to my mind.
done

> Y02d If one of maven deps remains, then the MavenArchetypeProvider could even be declared in it and not exposed in the public API at all.
coming later.
Comment 11 Tomas Stupka 2014-07-16 16:54:28 UTC
for the actual state see core-main branch maven_archetype_api_245153
Comment 12 Tomas Stupka 2014-07-17 16:37:05 UTC
ok, this got a bit too much ...

- Archetype is exposing types from o.apache.maven
- ArchetypeWizards is exporting a few more of our own friend api types - maven.model, swing.validation, ...
- last, but not least - Milos doesn't like the whole archetypes friend transition into a new module and the possible complication for module friends

lets try one more time and keep it for now as simple as possible:

- keep the o.n.m.maven.api.archetype friend package intact
- create a new public module
- delegate to o.n.m.maven.api.archetype.* and expose only what is possible/necessary
- everything else (the maven module, its friends in nb and in the remaining world) stays as it is

this was fun.
Comment 13 Tomas Stupka 2014-07-17 16:40:02 UTC
Created attachment 148108 [details]
new patch
Comment 14 Tomas Stupka 2014-07-18 13:23:29 UTC
guys, if nobody objects, i'll push on monday - tuesday ...
Comment 15 Jaroslav Tulach 2014-07-21 10:15:52 UTC
I would not expose the wild

public static void logUsage(String groupId, String artifactId, String version)

in the new API, unless we have a usage case of this method. Seems something API users won't care about. Otherwise perfect. Thanks a lot.
Comment 16 Tomas Stupka 2014-07-21 11:25:28 UTC
- logUsage(...) method removed
- and will rename modul to api.maven
Comment 17 Tomas Stupka 2014-07-21 11:51:56 UTC
fixed in core-main #d01c2c5e6e91
Comment 18 Quality Engineering 2014-07-23 02:09:49 UTC
Integrated into 'main-silver', will be available in build *201407230001* on http://bits.netbeans.org/dev/nightly/ (upload may still be in progress)

Changeset: http://hg.netbeans.org/main-silver/rev/d01c2c5e6e91
User: Tomas Stupka <tstupka@netbeans.org>
Log: Issue #245153 - No way to create a maven archetype without reflection/impl/friend dep