= !MapGuide RFC 74 - Move or rename resource avoid breaking links =

This page contains an change request (RFC) for the !MapGuide Open Source project.
More !MapGuide RFCs can be found on the [wiki:MapGuideRfcs RFCs] page.


== Status ==

||RFC Template Version||(1.0)||
||Submission Date||(July 7, 2009)||
||Last Modified||(Christine Bao Tue July 7 02:22:17 2009)||
||Author||Christine Bao||
||RFC Status||adopted||
||Implementation Status||completed||
||Proposed Milestone||2.2||
||Assigned PSC guide(s)||Tom Fukushima||
||'''Voting History'''||||
||+1||Tom, Andy, Kenneth, Paul, Trevor, Bruce||
||+0||||
||-0||||
||-1||||
||no vote||Jason, Bob, Harris ||

== Overview ==

This RFC adds a new API to ResourceService, overloading MoveResource to avoid breaking links.

== Motivation ==

Currently if move or rename resource, the other resources referencing to it are not updated and can't find the new location of the resource, thus they will not work anymore. For example, if move or rename a FeatureSource, the LayerDefinitions which references to this FeatureSource are not updated to use the new FeatureSource URL, and they can't work properly.
This RFC overload the ResourceService API MoveResource, adding a new parameter "bool cascade" to indicate whether update the referencing resources or not. The old API exist along with the new API to keep compatible.

== Proposed Solution ==

The modified ResourceService API is:
{{{
    /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
    /// \brief
    /// Moves an existing resource to another location.
    ///
    /// \remarks
    /// You can also use this method to rename a resource.
    ///
    /// <!-- Syntax in .Net, Java, and PHP -->
    /// \htmlinclude DotNetSyntaxTop.html
    /// virtual void MoveResource(MgResourceIdentifier sourceResource, MgResourceIdentifier destResource, bool overwrite, bool cascade);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude JavaSyntaxTop.html
    /// virtual void MoveResource(MgResourceIdentifier sourceResource, MgResourceIdentifier destResource, boolean overwrite, boolean cascade);
    /// \htmlinclude SyntaxBottom.html
    /// \htmlinclude PHPSyntaxTop.html
    /// virtual void MoveResource(MgResourceIdentifier sourceResource, MgResourceIdentifier destResource, bool overwrite, bool cascade);
    /// \htmlinclude SyntaxBottom.html
    ///
    /// \param sourceResource (MgResourceIdentifier)
    /// Resource to be moved. This can be a document
    /// or folder.
    /// <ul>
    ///    <li>If it is a folder, this method also moves the contents of the folder and all folders below it.</li>
    ///    <li>If it is a folder, you must include the trailing slash in the identifier.</li>
    /// </ul>
    /// \param destResource (MgResourceIdentifier)
    /// Where the resource should be moved to.
    /// \param overwrite (boolean/bool)
    /// Flag to determine whether or not the
    /// destination resource should be overwritten if
    /// it exists.
    /// \param cascade (boolean/bool)
    /// Flag to determine whether or not the
    /// referencing resource content should be updated.
    ///
    /// \return
    /// Returns nothing.
    ///
    /// <!-- Example (PHP) -->
    /// \htmlinclude PHPExampleTop.html
    /// This example moves the file
    /// Library://Geography/World.MapDefinition to
    /// Library://Atlas/Oceans.MapDefinition:
    /// \code
    /// // Assuming $resourceService has already been initialized
    /// $oldPath = new MgResourceIdentifier("Library://Geography/World.MapDefinition");
    /// $newPath = new MgResourceIdentifier("Library://Atlas/Oceans.MapDefinition");
    /// $resourceService->MoveResource($oldPath, $newPath, true, false);
    /// \endcode
    ///
    /// This example moves the folder Library://Geography/ to
    /// Library://World Geography/:
    /// \code
    /// $oldPath = new MgResourceIdentifier("Library://Geography/");
    /// $newPath = new MgResourceIdentifier("Library://World Geography/");
    /// $resourceService->MoveResource($oldPath, $newPath, true, true);
    /// \endcode
    ///
    /// This example renames Oceans.MapDefinition to Pacific
    /// Ocean.MapDefinition:
    /// \code
    /// /**************************************************************************/
    /// $oldPath = new MgResourceIdentifier("Library://Atlas/Oceans.MapDefinition");
    /// $newPath = new MgResourceIdentifier("Library://Atlas/Pacific Ocean.MapDefinition");
    /// $resourceService->MoveResource($oldPath, $newPath, true, true);
    /// \endcode
    /// \htmlinclude ExampleBottom.html
    ///
    /// \exception MgResourceNotFoundException
    /// \exception MgDuplicateResourceException
    /// \exception MgInvalidRepositoryTypeException
    /// \exception MgInvalidRepositoryNameException
    /// \exception MgInvalidResourcePathException
    /// \exception MgInvalidResourceNameException
    /// \exception MgInvalidResourceTypeException
    ///
    /// \note
    /// When copying a folder with the "overwrite" flag turned on, if
    /// the destination folder already exists, then only the children
    /// in the destination folder that have the same names as those
    /// in the source folder are overwritten. The rest should are
    /// left intact.
    ///
    virtual void MoveResource(MgResourceIdentifier* sourceResource,
        MgResourceIdentifier* destResource, bool overwrite, bool cascade) = 0;
}}}
[[BR]]

If cascade==true, not only this resource is moved, but also the referencing resources are found out and updated.[[BR]]
If cascade==false, it works exactly as what it's now.


Maestro keeps the link when move or rename resource, however it enumerates the referencing resources to client, and updates them one by one to server by a lot of individual requests. The disadvantage is obvious without a batch request:[[BR]]
1. Performance is bad.[[BR]]
2. The update may be incomplete if connection broken.


If cascade==false, which is the same as current behavior, it only needs to check whether user has permission for the moved resource. If cascade==true, before call this API it needs to check whether user has permission for both the moved resource and the referencing resources. The access permission is not checked during this API. 

== Implications ==

This new added API won't affect existing application.

== Test Plan ==

Test move or rename resource in Studio.

== Funding/Resources ==

Supplied by Autodesk.