uploadGeneratetoken: Add support to optionally create new revision

Backported from PR midasplatform#146

This commit updates the "uploadGeneratetoken" API introducing the new
parameter "create_additional_revision" allowing to optionally change
the default behavior and ensure a new revision is created when:
  - a bitstream associated with the file already exists on the server
  - and the checksum parameter is specified
  - and the item updated has at least one revision

Since the http uploader doesn't specify the "checksum" parameter, the
problem is only reproducible using the web API.

For example, considering the following configuration:

 folder
   |--- item1 --- revision1
   |                 |--- bitstream1 (filename1)
   |
   |--- item2 --- revision1
   |                 |--- bitstream2 (filename2)

By default, trying to associate bitstream1 with item2 will result in
this configuration:

 folder
   |--- item1 --- revision1
   |                 |--- bitstream1 (filename1)
   |
   |--- item2 --- revision1
   |                 |--- bitstream2 (filename2)
   |                 |--- bitstream1 (filename1)


By setting the option "create_additional_revision" to True, the
following configuration will be obtained:

 folder
   |--- item1 --- revision1
   |                 |--- bitstream1 (filename1)
   |
   |--- item2 -|--- revision1
   |           |     |--- bitstream2 (filename2)
   |           |
   |           |--- revision2
   |           |     |--- bitstream1 (filename1)

Author: jcfr

core/controllers/components/ApisystemComponent.php

@@ -286,6 +286,10 @@ function linkCreate($args)
             When passing the <b>folderid</b> param, the name of the newly created item,
             if not supplied, the item will have the same name as <b>filename</b>.
    * @param checksum (Optional) The md5 checksum of the file to be uploaded.
+   * @param create_additional_revision (Optional) When a <b>checksum</b> is passed and
+            the server already has the file, by default a reference to the existing
+            bitstream will be added to the latest revision. By setting
+            <b>create_additional_revision</b> to true, a new revision will be created.
    * @return An upload token that can be used to upload a file.
              If <b>folderid</b> is passed instead of <b>itemid</b>, a new item will be created
              in that folder, but the id of the newly created item will not be
@@ -372,14 +376,19 @@ function uploadGeneratetoken($args)
         // Otherwise an attacker could spoof the checksum and read a private bitstream with a known checksum.
         if($itemModel->policyCheck($existingBitstream->getItemrevision()->getItem(), $userDao, MIDAS_POLICY_READ))
           {
+          $create_additional_revision = isset($args['create_additional_revision']) ? $args['create_additional_revision'] : false;
           $revision = $itemModel->getLastRevision($item);
 
-          if($revision == false)
+          if($revision == false || $create_additional_revision)
             {
-            // Create new revision if none exists yet
+            // Create new revision if none exists yet or if user explicitly asked for creating a new revision when
+            // a bistream with the same checksum was found.
             Zend_Loader::loadClass('ItemRevisionDao', BASE_PATH.'/core/models/dao');
             $revision = new ItemRevisionDao();
-            $revision->setChanges('Initial revision');
+            if($create_additional_revision == false)
+              {
+              $revision->setChanges('Initial revision');
+              }
             $revision->setUser_id($userDao->getKey());
             $revision->setDate(date("Y-m-d H:i:s"));
             $revision->setLicenseId(null);

modules/api/controllers/components/ApiComponent.php

@@ -307,6 +307,10 @@ function linkCreate($args)
             When passing the <b>folderid</b> param, the name of the newly created item,
             if not supplied, the item will have the same name as <b>filename</b>.
    * @param checksum (Optional) The md5 checksum of the file to be uploaded.
+   * @param create_additional_revision (Optional) When a <b>checksum</b> is passed and
+            the server already has the file, by default a reference to the existing
+            bitstream will be added to the latest revision. By setting
+            <b>create_additional_revision</b> to true, a new revision will be created.
    * @return An upload token that can be used to upload a file.
              If <b>folderid</b> is passed instead of <b>itemid</b>, a new item will be created
              in that folder, but the id of the newly created item will not be