DSID not datastream. (#680)

* DSID not datastream.

* Catch the typed exception and return FALSE for a deprecation cycle.

* Move the exception for easy removal later.

* Update as per code review feedback.

* Update README.

* May.

* English.

README.md

@@ -55,6 +55,8 @@ Further documentation for this module is available at [our wiki](https://wiki.du
 
 ## Troubleshooting/Issues
 
+NOTE: There has been a function signature change for the `ingestDatastream` function within Tuque which will be deprecated after the 7.x-1.10 release. To read about it in detail please see the [JIRA ticket](https://jira.duraspace.org/browse/ISLANDORA-1995). For the time being there is a warning stating that this will become deprecated and that code that utilizes this specific behavior should be updated. Once this code is updated the `islandora_deprecation_return_false_when_datastream_exists` variable may be set to FALSE so the warning no longer displays. An example for doing this with drush: `drush vset islandora_deprecation_return_false_when_datastream_exists FALSE`. 
+
 Having problems or solved a problem? Check out the Islandora google groups for a solution.
 
 * [Islandora Group](https://groups.google.com/forum/?hl=en&fromgroups#!forum/islandora)

includes/tuque_wrapper.inc

@@ -240,7 +240,15 @@ class IslandoraFedoraObject extends FedoraObject {
       return $ret;
     }
     catch (Exception $e) {
-      watchdog('islandora', 'Failed to ingest datastream @datastream on object: @pid</br>code: @code<br/>message: @msg', array(
+      if ($e instanceof DatastreamExistsException && variable_get('islandora_deprecation_return_false_when_datastream_exists', TRUE)) {
+        $message = format_string('The datastream @dsid already exists on the object: @pid. As of 7.x-1.10 the function signature for ingestDatastream will be changed from returning FALSE on failure to throwing an exception.', array(
+          '@dsid' => $datastream->id,
+          '@pid' => $object->id,
+        ));
+        trigger_error(filter_xss($message), E_USER_DEPRECATED);
+        return FALSE;
+      }
+      watchdog('islandora', 'Failed to ingest datastream @dsid on object: @pid</br>code: @code<br/>message: @msg', array(
         '@pid' => $object->id,
         '@dsid' => $datastream->id,
         '@code' => $e->getCode(),