[LMS-2238] updated javadoc comment to reflect reality

SVN: 21630

datastore_server/source/java/ch/systemsx/cisd/openbis/dss/generic/shared/StandardShareFinder.java

@@ -30,17 +30,24 @@ import ch.systemsx.cisd.openbis.dss.generic.shared.utils.Share.ShufflePriority;
 import ch.systemsx.cisd.openbis.generic.shared.dto.SimpleDataSetInformationDTO;
 
 /**
- * A share finder working in the following way
+ * A share finder implementation. The search algorithm considers all shares with enough free space
+ * as potential result "candidates" (The free space of the data set "home" share is increased by the
+ * data set size). The result (which is simply the best candidate) is elected by the following
+ * rules:
  * 
  * <pre>
- * 1. Try to find an extension share before trying to find incoming shares.
- * 2. Try to find share with speed respecting speed hint. If there are more than one choose that 
- * one with speed closest to absolute value of speed hint. 
- * 3. Otherwise choose the share with most free space.
+ * 1. An extension share is preferred above an incoming share.
+ * 2. A share whose speed matches the speed requirements of the data set is preferred. If there is more 
+ * than one share matching in the same way then choose the one with speed closest to absolute value of speed hint. 
+ * 3. If all candidates have the same parameters for (1) and (2) choose the share with most free space.
  * </pre>
  * 
  * The priority of points (1) and (2) can be swapped if the current location of the data set is an
  * incoming share and it has a shuffle priority of {@link ShufflePriority#SPEED}.
+ * <p>
+ * Generally the {@link StandardShareFinder} tends to move data sets from incoming to extension
+ * shares. A data set can only be moved from extension to incoming share by an unarchiving operation
+ * if at the time of unarchiving all extension shares (regardless of their speeds) are full.
  * 
  * @author Kaloyan Enimanev
  */
@@ -78,10 +85,10 @@ public class StandardShareFinder implements IShareFinder
         if (false == candidates.isEmpty())
         {
             CandidateShare bestCandidate = Collections.min(candidates);
-            Share bestDestination = bestCandidate.getShare();
-            if (false == bestDestination.equals(homeShare))
+            Share bestDestinationShare = bestCandidate.getShare();
+            if (false == bestDestinationShare.equals(homeShare))
             {
-                return bestDestination;
+                return bestDestinationShare;
             }
         }
         return null;

datastore_server/sourceTest/java/ch/systemsx/cisd/openbis/dss/generic/shared/StandardShareFinderTest.java

@@ -76,6 +76,28 @@ public class StandardShareFinderTest extends AbstractIShareFinderTestCase
         assertShareFoundForDataSet(null, dataSet("2", megaBytes(900), -50));
     }
 
+    @Test
+    public void testMoveToExtensionShareWithMoreSpace()
+    {
+        shares =
+                Arrays.asList(incomingShare("1", megaBytes(2000), 50, ShufflePriority.SPEED),
+                        extensionShare("2", megaBytes(3000), 40),
+                        extensionShare("3", megaBytes(5000), 40),
+                        extensionShare("4", megaBytes(4000), 40));
+        assertShareFoundForDataSet("3", dataSet("2", megaBytes(900), 60));
+    }
+
+    @Test
+    public void testMoveToExtensionShareWithBetterSpeedMatch()
+    {
+        shares =
+                Arrays.asList(incomingShare("1", megaBytes(2000), 50, ShufflePriority.SPEED),
+                        extensionShare("2", megaBytes(3000), 40),
+                        extensionShare("3", megaBytes(3000), 45),
+                        extensionShare("4", megaBytes(1000), 50));
+        assertShareFoundForDataSet("4", dataSet("2", megaBytes(900), 60));
+    }
+
     @Test
     public void testShuffleToIncomingShareWithMoreSpace()
     {