Clarify purpose of Sequence ID

dspace-api/src/main/java/org/dspace/content/Bitstream.java

@@ -99,8 +99,12 @@ public class Bitstream extends DSpaceObject implements DSpaceObjectLegacySupport
     }
 
     /**
-     * Get the sequence ID of this bitstream
+     * Get the sequence ID of this bitstream. The sequence ID is a unique (within an Item) integer that references
+     * this bitstream. It acts as a "persistent" identifier within the Item for this Bitstream (as Bitstream names
+     * are not persistent). Because it is unique within an Item, sequence IDs are assigned by the ItemService.update()
+     * method.
      *
+     * @see org.dspace.content.ItemServiceImpl#update(Context, Item)
      * @return the sequence ID
      */
     public int getSequenceID() {
@@ -112,8 +116,12 @@ public class Bitstream extends DSpaceObject implements DSpaceObjectLegacySupport
     }
 
     /**
-     * Set the sequence ID of this bitstream
+     * Set the sequence ID of this bitstream. The sequence ID is a unique (within an Item) integer that references
+     * this bitstream. While this method is public, it should only be used by ItemService.update() or other methods
+     * which validate the uniqueness of the ID within the associated Item. This method itself does not validate
+     * uniqueness of the ID, nor does the underlying database table.
      *
+     * @see org.dspace.content.ItemServiceImpl#update(Context, Item)
      * @param sid the ID
      */
     public void setSequenceID(int sid) {

dspace-api/src/main/java/org/dspace/content/ItemServiceImpl.java

@@ -496,7 +496,8 @@ public class ItemServiceImpl extends DSpaceObjectServiceImpl<Item> implements It
 
         super.update(context, item);
 
-        // Set sequence IDs for bitstreams in item
+        // Set sequence IDs for bitstreams in Item. To guarantee uniqueness,
+        // sequence IDs are assigned in sequential order (starting with 1)
         int sequence = 0;
         List<Bundle> bunds = item.getBundles();
 
@@ -513,8 +514,6 @@ public class ItemServiceImpl extends DSpaceObjectServiceImpl<Item> implements It
 
         // start sequencing bitstreams without sequence IDs
         sequence++;
-
-
         for (Bundle bund : bunds) {
             List<Bitstream> streams = bund.getBitstreams();
 
@@ -1561,4 +1560,4 @@ prevent the generation of resource policy entry values with null dspace_object a
         metadataValue.setLanguage(Item.ANY);
         return metadataValue;
     }
-}
+}

dspace-server-webapp/src/main/java/org/dspace/app/rest/model/BitstreamRest.java

@@ -28,6 +28,7 @@ public class BitstreamRest extends DSpaceObjectRest {
     private BitstreamFormatRest format;
     private Long sizeBytes;
     private CheckSumRest checkSum;
+    // sequenceId is READ_ONLY because it is assigned by the ItemService (as it must be unique within an Item)
     @JsonProperty(access = Access.READ_ONLY)
     private Integer sequenceId;
 
@@ -81,4 +82,4 @@ public class BitstreamRest extends DSpaceObjectRest {
     public String getType() {
         return NAME;
     }
-}
+}