Re: Use of standards in the Maven core

[Jesse Glick <je...@oracle.com>]

Reposting to an old thread, since I am still running into what seems to be Maven 2 debris in the APIs.

On 11/19/2010 02:19 PM, Kristian Rosenvold wrote:
> if it hurts you, make a patch; documentation upgrade, javadoc or code changes

The difficulty with submitting Javadoc changes is that if you need the Javadoc you probably are not going to be sure what it should say. :-) I considered submitting a 
pull request to github.com/apache/maven-3 basically documenting org.apache.maven.artifact.resolver.ArtifactResolutionRequest.setMirrors to say "do not trust that I do 
anything", but it is not obvious under which circumstances it actually does what it sounds like. A little story:

I had a call to org.apache.maven.repository.RepositorySystem.resolve. Undocumented, but it seems to download artifacts to the local repository (when not already present), 
a generally useful task. (While the interface is in Maven Core, the only impl is in Maven Compat and named - ominously - LegacyRepositorySystem. If it is supposed to be 
deprecated, there is no Javadoc saying so, or suggesting a replacement, so I stick with it for now.)

However yesterday I noticed that it was not working on an artifact in Central that I knew existed and in fact was very likely cached in my local Nexus. For reasons 
irrelevant here the remoteRepositories in the call included a definition of Central as http://central/ (taken from Nexus installation FAQs), but the actual URL should not 
have mattered since I have a mirror definition. Therefore my local mirror settings were being ignored.

Taking a look at the call to resolve, it is given an ArtifactResolutionRequest. I had a org.apache.maven.settings.Settings object handy with the right mirror definitions, 
so code completion and common sense would dictate that I should call request.setMirrors(settings.getMirrors())... but this had no effect.

Time for the debugger. I set the mirrors on the request and follow what happens. The list of mirrors is read in org.apache.maven.artifact.resolver.DefaultArtifactResolver 
but this line of code is never encountered. Instead, when request.isResolveRoot() returns true - the default value - an attempt is made to download the artifact _before_ 
considering the mirrors, which in this case fails and returns early from the resolve method. I could try to not "resolve the root", whatever that means (no Javadoc), but 
this just looks wrong. Anyway even if the request is not "resolving the root", the mirrors are considered only if the request also isResolveTransitively(), which I do not 
want in general.

So I set a breakpoint on org.apache.maven.artifact.resolver.ArtifactResolutionException. This gets thrown from another overload of "resolve" as a result of a 
org.sonatype.aether.resolution.ArtifactResolutionException, so set a breakpoint on that. This is thrown from org.sonatype.aether.impl.internal.DefaultArtifactResolver 
(now you see why I am giving fully-qualified class names), apparently due to a org.sonatype.aether.transfer.ArtifactTransferException which seems like the expected 
low-level error. When it gets thrown there is no sign of the mirrors, just http://central/; but local variables include a org.sonatype.aether.RepositorySystemSession 
which has a NullMirrorSelector, which must be wrong.

Presumably something was supposed to call org.sonatype.aether.util.DefaultRepositorySystemSession.setMirrorSelector; nothing in the call stack does so. So who calls this 
with a nontrivial selector? org.apache.maven.DefaultMaven.newRepositorySession does, and shows how it can be used. But where do I get that session? From prior experience 
I knew that org.apache.maven.plugin.LegacySupport.setSession is needed for many calls from Maven Compat. And indeed, http://hg.netbeans.org/main-silver/rev/9d464b81555e 
makes the mirror settings be honored, basically passing them in thread-local state.

So what is the upshot? Maybe org.apache.maven.repository.RepositorySystem.resolve needed to be deprecated to begin with. (Replaced perhaps by 
org.sonatype.aether.RepositorySystem.resolveArtifact?) It is used in one place in Maven Core - which, incidentally, does call request.setMirrors, but also 
setResolveRoot(false) and setResolveTransitively(true) and so conveniently triggering the conditions for the mirrors to be read! But this is in 
DefaultProjectDependenciesResolver, and ProjectDependenciesResolver is never called - while again in Core and not deprecated, meaning the mold may be deeper in the cheese.


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org

Re: Use of standards in the Maven core

[Kristian Rosenvold <kr...@gmail.com>]

I am wondering about what kind of documentation you are thinking about.
We have so much documentation that I hardly know where to stop.

I think "blind" javadoc is just so much baloney. If there are any 
specific use cases that require documentation I'm happy to discuss
that. 

Kristian



ti., 27.09.2011 kl. 09.24 -0400, skrev Mark H. Wood:
> On Tue, Sep 27, 2011 at 07:49:37AM -0400, Jesse Glick wrote:
> > On 11/19/2010 02:19 PM, Kristian Rosenvold wrote:
> > > if it hurts you, make a patch; documentation upgrade, javadoc or code changes
> > 
> > The difficulty with submitting Javadoc changes is that if you need
> > the Javadoc you probably are not going to be sure what it should
> > say. :-)
> 
> I am always amused (and saddened) to read that the documentation
> should be written by those who do not understand the code.
> 
> It is possible to do this tolerably well.  It's exhausting, but it
> *is* an effective way to get to know the product better --
> eventually.  And there are still gaps:  places where it's simply not
> feasible to divine what the author was thinking when he wrote *that*.
> 



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org

Re: Use of standards in the Maven core

["Mark H. Wood" <mw...@IUPUI.Edu>]

On Tue, Sep 27, 2011 at 07:49:37AM -0400, Jesse Glick wrote:
> On 11/19/2010 02:19 PM, Kristian Rosenvold wrote:
> > if it hurts you, make a patch; documentation upgrade, javadoc or code changes
> 
> The difficulty with submitting Javadoc changes is that if you need
> the Javadoc you probably are not going to be sure what it should
> say. :-)

I am always amused (and saddened) to read that the documentation
should be written by those who do not understand the code.

It is possible to do this tolerably well.  It's exhausting, but it
*is* an effective way to get to know the product better --
eventually.  And there are still gaps:  places where it's simply not
feasible to divine what the author was thinking when he wrote *that*.

-- 
Mark H. Wood, Lead System Programmer   mwood@IUPUI.Edu
Asking whether markets are efficient is like asking whether people are smart.