change:

- 'createLocationFromPosition' ---> 'tryCreateLocationFromPosition'.
- 'createLocationFromMatrixCoordinate' ---> 'tryCreateLocationFromMatrixCoordinate'.

SVN: 3215

bds/source/java/ch/systemsx/cisd/bds/hcs/Location.java

@@ -45,18 +45,25 @@ public final class Location
         this.y = y;
     }
 
-    /** For given <var>position</var> in given <code>geometry</code> returns corresponding <code>Location</code>. */
-    public static final Location createLocationFromPosition(final int position, final Geometry geometry)
+    /**
+     * For given <var>position</var> in given <code>geometry</code> returns corresponding <code>Location</code>.
+     * 
+     * @return <code>null</code> if position is out of range.
+     */
+    public static final Location tryCreateLocationFromPosition(final int position, final Geometry geometry)
     {
         assert geometry != null : "Given geometry can not be null.";
         final int columns = geometry.getColumns();
         final int max = columns * geometry.getRows();
-        assert position > 0 && position < max : String.format("Given position %d is out of range (%s).", position,
-                geometry);
-        final int modulo = position % columns;
-        final int x = modulo == 0 ? columns : modulo;
-        final int y = (int) Math.ceil(position / (float) columns);
-        return new Location(x, y);
+        // Given position is within the range.
+        if (position > 0 && position < max)
+        {
+            final int modulo = position % columns;
+            final int x = modulo == 0 ? columns : modulo;
+            final int y = (int) Math.ceil(position / (float) columns);
+            return new Location(x, y);
+        }
+        return null;
     }
 
     /**
@@ -65,7 +72,7 @@ public final class Location
      * 
      * @return <code>null</code> if given <var>coordinate</var> is not a matrix coordinate.
      */
-    public static final Location createLocationFromMatrixCoordinate(final String coordinate)
+    public static final Location tryCreateLocationFromMatrixCoordinate(final String coordinate)
     {
         assert coordinate != null : "Coordinate can not be null.";
         final String[] split = StringUtilities.splitMatrixCoordinate(coordinate);

bds/sourceTest/java/ch/systemsx/cisd/bds/hcs/LocationTest.java

@@ -71,19 +71,19 @@ public final class LocationTest
         final Geometry geometry = new Geometry(4, 5);
         try
         {
-            Location.createLocationFromPosition(1, null);
+            Location.tryCreateLocationFromPosition(1, null);
             fail("Null geometry not allowed.");
         } catch (AssertionError ex)
         {
             // Nothing to do here.
         }
-        assertEquals(new Location(2, 3), Location.createLocationFromPosition(12, geometry));
-        assertEquals(new Location(5, 3), Location.createLocationFromPosition(15, geometry));
-        assertEquals(new Location(2, 1), Location.createLocationFromPosition(2, geometry));
-        assertEquals(new Location(1, 2), Location.createLocationFromPosition(6, geometry));
+        assertEquals(new Location(2, 3), Location.tryCreateLocationFromPosition(12, geometry));
+        assertEquals(new Location(5, 3), Location.tryCreateLocationFromPosition(15, geometry));
+        assertEquals(new Location(2, 1), Location.tryCreateLocationFromPosition(2, geometry));
+        assertEquals(new Location(1, 2), Location.tryCreateLocationFromPosition(6, geometry));
         try
         {
-            Location.createLocationFromPosition(100, geometry);
+            Location.tryCreateLocationFromPosition(100, geometry);
             fail("Position is out of range.");
         } catch (AssertionError ex)
         {
@@ -96,17 +96,17 @@ public final class LocationTest
     {
         try
         {
-            Location.createLocationFromMatrixCoordinate(null);
+            Location.tryCreateLocationFromMatrixCoordinate(null);
             fail("Coordinate can not be null.");
         } catch (AssertionError ex)
         {
             // Nothing to do here.
         }
-        assertNull(Location.createLocationFromMatrixCoordinate(""));
-        assertNull(Location.createLocationFromMatrixCoordinate("8"));
-        assertNull(Location.createLocationFromMatrixCoordinate("M"));
-        assertEquals(new Location(2, 1), Location.createLocationFromMatrixCoordinate("A02"));
-        assertEquals(new Location(7, 26), Location.createLocationFromMatrixCoordinate("z7"));
-        assertEquals(new Location(34, 15), Location.createLocationFromMatrixCoordinate("O34"));
+        assertNull(Location.tryCreateLocationFromMatrixCoordinate(""));
+        assertNull(Location.tryCreateLocationFromMatrixCoordinate("8"));
+        assertNull(Location.tryCreateLocationFromMatrixCoordinate("M"));
+        assertEquals(new Location(2, 1), Location.tryCreateLocationFromMatrixCoordinate("A02"));
+        assertEquals(new Location(7, 26), Location.tryCreateLocationFromMatrixCoordinate("z7"));
+        assertEquals(new Location(34, 15), Location.tryCreateLocationFromMatrixCoordinate("O34"));
     }
 }