[LANG-1509] Add ObjectToStringComparator. (#483)

* [LANG-1509] Add ObjectToStringComparator.

* [LANG-1509] Add ObjectToStringComparator.

Repackage.

* [LANG-1509] Add ObjectToStringComparator.

Avoid NPE.

* [LANG-1509] Add ObjectToStringComparator.

Clean ups.

* Spotbugs: toString() can return null!

pom.xml

@@ -760,6 +760,13 @@
         <groupId>com.github.spotbugs</groupId>
         <artifactId>spotbugs-maven-plugin</artifactId>
         <version>${spotbugs.plugin.version}</version>
+        <dependencies>
+          <dependency>
+            <groupId>com.github.spotbugs</groupId>
+            <artifactId>spotbugs</artifactId>
+            <version>4.0.0-beta4</version>
+         </dependency>
+        </dependencies>        
         <configuration>
           <excludeFilterFile>${basedir}/spotbugs-exclude-filter.xml</excludeFilterFile>
         </configuration>

spotbugs-exclude-filter.xml

@@ -146,4 +146,11 @@
     <Method name="equals" />
     <Bug pattern="NP_EQUALS_SHOULD_HANDLE_NULL_ARGUMENT" />
   </Match>
+  
+  <!-- Reason: toString() can return null! -->
+  <Match>
+    <Class name="org.apache.commons.lang3.compare.ObjectToStringComparator" />
+    <Method name="compare" />
+    <Bug pattern="RCN_REDUNDANT_NULLCHECK_OF_NONNULL_VALUE" />
+  </Match>
 </FindBugsFilter>

src/main/java/org/apache/commons/lang3/compare/ObjectToStringComparator.java

@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.lang3.compare;
+
+import java.io.Serializable;
+import java.util.Comparator;
+
+/**
+ * Compares Object's {@link Object#toString()} values.
+ *
+ * This class is stateless.
+ *
+ * @since 3.10
+ */
+public final class ObjectToStringComparator implements Comparator<Object>, Serializable {
+
+    /**
+     * Singleton instance.
+     *
+     * This class is stateless.
+     */
+    public static final ObjectToStringComparator INSTANCE = new ObjectToStringComparator();
+
+    /**
+     * For {@link Serializable}.
+     */
+    private static final long serialVersionUID = 1L;
+
+    @Override
+    public int compare(final Object o1, final Object o2) {
+        if (o1 == null && o2 == null) {
+            return 0;
+        }
+        if (o1 == null) {
+            return 1;
+        }
+        if (o2 == null) {
+            return -1;
+        }
+        final String string1 = o1.toString();
+        final String string2 = o2.toString();
+        // No guarantee that toString() returns a non-null value, despite what Spotbugs thinks.
+        if (string1 == null && string2 == null) {
+            return 0;
+        }
+        if (string1 == null) {
+            return 1;
+        }
+        if (string2 == null) {
+            return -1;
+        }
+        return string1.compareTo(string2);
+    }
+}

src/test/java/org/apache/commons/lang3/compare/ObjectToStringComparatorTest.java

@@ -0,0 +1,73 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.commons.lang3.compare;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+/**
+ * Tests {@link ObjectToStringComparator}.
+ */
+public class ObjectToStringComparatorTest {
+
+    private static class Thing {
+
+        final String string;
+
+        Thing(final String string) {
+            this.string = string;
+        }
+
+        @Override
+        public String toString() {
+            return string;
+        }
+    }
+
+    @Test
+    public void testNull() {
+        final List<Thing> things = Arrays.asList(null, new Thing("y"), null);
+        Collections.sort(things, ObjectToStringComparator.INSTANCE);
+        assertEquals("y", things.get(0).string);
+        assertEquals(null, things.get(1));
+        assertEquals(null, things.get(2));
+    }
+
+    @Test
+    public void testNullToString() {
+        final List<Thing> things = Arrays.asList(new Thing(null), new Thing("y"), new Thing(null));
+        Collections.sort(things, ObjectToStringComparator.INSTANCE);
+        assertEquals("y", things.get(0).string);
+        assertEquals(null, things.get(1).string);
+        assertEquals(null, things.get(2).string);
+    }
+
+    @Test
+    public void testSortCollection() {
+        final List<Thing> things = Arrays.asList(new Thing("z"), new Thing("y"), new Thing("x"));
+        Collections.sort(things, ObjectToStringComparator.INSTANCE);
+        assertEquals("x", things.get(0).string);
+        assertEquals("y", things.get(1).string);
+        assertEquals("z", things.get(2).string);
+    }
+}