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 27687 - Undeprecate Repository findResource (and findAllResources) method
Summary: Undeprecate Repository findResource (and findAllResources) method
Status: RESOLVED FIXED
Alias: None
Product: platform
Classification: Unclassified
Component: Filesystems (show other bugs)
Version: 3.x
Hardware: PC All
: P3 blocker (vote)
Assignee: Peter Zavadsky
URL:
Keywords: API
Depends on:
Blocks: 27643
  Show dependency tree
 
Reported: 2002-09-30 14:33 UTC by Peter Zavadsky
Modified: 2008-12-22 21:56 UTC (History)
4 users (show)

See Also:
Issue Type: TASK
Exception Reporter:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description Peter Zavadsky 2002-09-30 14:33:46 UTC
David's snippet from issue #29604:

Sorry but what is the connection between this and
classpath related
issue?

    /** Searches for the given resource among all
filesystems.
    * @see FileSystem#findResource
    * @param name a name of the resource
    * @return file object or <code>null</code> if
the resource can not
be found
    * @deprecated Please use the <a
href="http://www.netbeans.org/download/dev/javadoc/JavaSupportAPIs/org/netbeans/api/java/classpath/api.html">ClassPath
API</a> instead.
    */
    public final FileObject findResource(String
name) {


Shouldn't this be undeprecated? It is similar to
toString() issue -
bad usage does not mean we should leave it
deprecated. I am creating
an issue to check all usages in core/openide - 27643.
Comment 1 Peter Zavadsky 2002-10-02 08:53:51 UTC
There is also findAllResources method, which should be undeprecated too.
Comment 2 Peter Zavadsky 2002-10-02 09:22:29 UTC
Fixed in [trunk]

openide/../filesystems/Repository.java 1.42
Comment 3 Jesse Glick 2002-10-02 18:47:09 UTC
I do not agree with this change. What purpose do these methods have if
the Classpath API makes the meaning of the roots of filesystems
arbitrary? What use would a method be in Windows "find all directories
named FOO underneath any drive, e.g. C:\FOO, A:\FOO, etc."? It would
be very strange and misleading. If anyone is calling either of these
methods, it is very likely that the developer was thinking of e.g.
ClassLoader.getAllResources(). Before the classpath change, this would
work - return something meaningful. Now it will not return anything
meaningful. Therefore the method is not useful any more and should be
deprecated.

In the unlikely case that someone really wanted to find files with a
certain name beneath every mounted filesystem, knowing that these
having nothing to do with classpath resource paths, it is easy to just
iterate through mounted filesystems and look for the file. So I don't
think that is a counterargument.

Deprecation serves as (1) a reminder to outside developers that the
method is probably not what they want to use and calls to it should be
replaced by better code, (2) a reminder to us to delete the method
some day (i.e. if we had to do it all over again, we would never have
written the method). Repository.findResource and findAllResources
satisfy both these conditions IMHO.
Comment 4 Peter Zavadsky 2002-10-03 08:44:25 UTC
I guess it shouldn't be thought it has anything to do with classpath.
It was thought before that way, and is wrong. Those methods find
arbitrary resources, not classes.

What is wrong when if somebody wants all resources named foo and she
get all of them (i.e. both fileobjects A:\foo and C:\foo from your
example)? I think that's correct.

Moreover, these methods just delegate the actual processing to
FileSystem.findResource which is not deprecated, thus supposed to work
 correctly
Comment 5 Jesse Glick 2002-12-09 19:44:17 UTC
Sorry, but I still disagree with the removal of @deprecated here.

"What is wrong when if somebody wants all resources named foo and she
get all of them (i.e. both fileobjects A:\foo and C:\foo from your
example)? I think that's correct." - yes, that is the correct outcome
according to the current Javadoc.

The problem is that nobody ever wants this outcome in practice. Very
likely everyone who ever calls this method is doing so because it
*used to* do something useful with the classpath. There is no longer
any plausible reason to call this method; the only people calling it
are wrong. Don't believe me? Search nb_all/*/{,src/}**/*.java for uses
of Repository.findResource and look at how it is used. And come up
with a realistic legitimate usage for it now.

That seems a clear case for deprecation. The fact that its behavior is
precisely specified is nice, but not relevant. What is relevant is
that all (or at least nearly all) uses of the method should be
replaced by different code, which is what @deprecated is good for:

http://java.sun.com/j2se/1.4/docs/guide/misc/deprecation/deprecation.html

FileSystem.findResource *does* do something which is still useful -
though some callers are also probably abusing it, some are using it
legitimately, so we cannot deprecate just the bad uses (except by
deprecating it but introducing an exact copy with a more meaningful name).

FileObject.toString is trickier, since Object.toString is not
deprecated, javac will not warn about implicit use from the "+"
operator, and the method is useful for debugging where you do not care
about the exact value. However I still tend toward favoring
deprecation of FO.toString, to force at least most people to check
their usage of it before replacing with getPath().

All right, I'll shut up now. :-)
Comment 6 David Strupl 2002-12-10 08:08:51 UTC
If you feel strongly that it should be deprecated I will give up since
I don't care that much. But I beleive the method should remain there
for quite a long time before it is removed since its presence does no
harm and both javadoc and implementation are (and were) fine.
Comment 7 Jesse Glick 2002-12-10 17:42:22 UTC
I don't have a strong opinion about deleting the method vs.
deprecating, only about leaving undeprecated... Evan suggests that
easily-abused methods just be deleted to make for cleaner failures,
but who knows. Depends on how we deal with missing methods - there was
a proposal for some system to automatically disable modules with
linkage errors or something like this.

I should point out that even under pre-Classpath API NetBeans,
Repository.findResource (ditto findAllResources) should probably have
been deprecated in favor of the corresponding method in
FileSystemCapability, which requires you to think about which actual
capabilities you are looking for.

Again, the issue is not whether the implementation "works" according
to the Javadoc, which in 3.4 reads:

"Searches for the given resource among all filesystems."

and links to FileSystem.findResource which reads:

"Finds file when its resource name is given. The name has the usual
format for the ClassLoader.getResource(String) method. So it may
consist of "package1/package2/filename.ext". If there is no package,
it may consist only of "filename.ext"."

[note that this certainly implies a relation to the classpath]

so much as the fact that performing this sequence of steps - getting
all filesystems and asking each to look for a contained file with a
given relative name - is as of 4.0 a *deprecated activity*, almost
sure to end in either failure or a misleading result, except in very
artifically contrived cases. "When to Deprecate" in the JDK docs
includes as the last reason:

"the old API encourages very bad coding practices"

Calling Repository.findResource certainly "encourages" you to do the
above action - in fact it does it - and I would argue that the above
action is a very bad coding practice - since it used to do something
commonly useful for modules and now it does not (while there is a
different set of calls which does).

If localfs really simulates the effect of the old classpath
accurately, then I guess deprecation is much better than deletion.

Hmm, maybe I should think twice before saying "I'll shut up now"...