*** Issue 22851 has been marked as a duplicate of this issue. ***

Increasing the priority to P3, since this bug cause the vcsgeneric's
recursive commands to behave highly unreliably.
It's important to be fixed soon for 3rd party products.

Added "FFJ40_WAV" keyword. I request to be waived for the FFJ 4.0
(Orion) release due to the complexity of the fix. It's too late to do
it into 4.0.
I request a fix would be included into 4.0 patch.

The main problems are (excerpt from the document at
http://vcscore.netbeans.org/doc/CacheArchitecture.html):
1) There's a 1-to-1 relationship between the cache objects and the
FileObjects in the filesystem,
2) The shrinking of cache is done automatically: There's a special
thread that periodically goes through the ReferenceQueue and if some
fileobjects get removed, it removes the corresponding cacheObjects as
well.

Proposed solution:
1) Assure, that the directory content does not disappear while the
cache directory is strongly referenced.
2) The content of a cache directory is lost as soon as there is no
more strong reference to it. The applied level of that directory is
reverted to NONE.
3) The cache files will never disappear unless their parent cache
directory disappears. Thus the cache directory content will be either
complete or empty with NONE applied level.
4) Each cache directory will be bound with the corresponding
FileObject so that the cache directory will stay alive while the
FileObject exists.
5) There will be a new method CacheHandler.getCacheFile(File file, int
strategy, String type, Object dirLocker). If a recursive strategy will
be requested, the whole hierarchical cache tree structure will be
"locked" (i.e. held in memory) by the "dirLocker" object. This will
assure, that the cache will not shrink until dirLocker is released
from memory.

I'm going to implement the proposed changes in the "experimental"
branch of vcscore module and merge them as soon as the new
architecture will work.

Any comments/suggestions to the proposed solution are welcomed.

I have decided to modify a little the proposed solution:
- The CacheFiles are also held on WeakReferences, this is mainly due
to the fact, that having opened just one file from every folder would
keep the whole cache hierarchy in memory.
- The user of the cache should never see, that some cache files were
released from memory - they will be reloaded from the disk cache when
sb. will ask for children.
- The "locker" concept is introduced to all methods, that retrieve the
cache dir content. It's purpose is purely for the efficiency. It will
prevent the cache content from being garbage-collected, thus the cache
content will not be reloaded from disk each time sb. asks for
children.

Implementation on "experimental" branch updated, I'm going to do some
tests of it. Comments are welcomed.

Tests seems to be successfull, thus I've merged the experimental
branch to the main trunk.
The caching folder in javacvs adjusted to be compatible with this
change.

As the result, the cache should be freed from memory when not
referenced as it is now, but any strong references to CacheDir and
CacheFile objects will disallow them to be released from memory.
When CacheDir is asked for it's children, it will reload them
automatically from the disk cache in case they were released from
memory.

Fixed in dev build on May 31.

I think it works significantly better, because recursive commands are
reliable now. I was able to "Add" very complex directory structure
without error, but on the other hand I had some problems with status
updates and checking it out back from the root of my filesystem. I am
gonna reopen issue #22851 for that purpose.
Verified in development build #200206050100 of NetBeans 3.4.

Resolved for 3.4.x or earlier, no new info since then -> closing.