[platform-core-dev] Replaced IResource.DEEP with IResource.SHALLOW

["John Arthorne" <John_Arthorne@xxxxxxx>]

Last build we introduced a new update flag, IResource.DEEP, for dealing
with how linked resources are copied and moved.  When the DEEP flag was
specified, the underlying contents of the linked resource would be copied
or moved.  The result of a DEEP copy/move would be a non-linked resource
under the project's root content location.  When DEEP was not specified, it
would only copy/move the link itself, and the destination would be a linked
resource pointing to the same file system location as the source.

The problem with this arrangement crops up when non link-aware clients
(such as those based on Eclipse 1.0 or 2.0), use copy and move.  Without
any flags, copy and move would fail if you tried to copy or move a linked
resource into a folder, since linked resources must have a project as their
immediate parent.

To prevent exceptions for older clients, we have decided to remove the DEEP
flag, and replace it with a new IResource.SHALLOW flag.  This flag has the
opposite meaning from IResource.DEEP.  In other words, the default
behaviour of copy/move (when no flags are specified) has changed to be DEEP
by default.  This new behaviour has been released to the HEAD stream and
will be in the next integration build.  The DEEP flag has been marked as
deprecated, AND WILL BE REMOVED AFTER THE NEXT INTEGRATION BUILD.

Note that this new behaviour is not a panacea for clients of our API.  The
normal behaviour that end users will expect when copying or moving links
(think of *nix symbolic links or windows short-cuts), is to perform a
shallow copy or move.  Shallow copy/move should still generally be
considered as the more likely choice.  As an example, renaming a project
(equivalent to a move), will now by default convert all linked resources
into non-linked resources under the project's root content area (this is a
DEEP move).  Eclipse 2.1 clients should revisit their uses of IResource
copy and move, and consider their effect in the face of linked resources.

The bug reference for this change is:

http://dev.eclipse.org/bugs/show_bug.cgi?id=26933