From e59eb4971fc6fffb822bceea672f00f89ba0770a Mon Sep 17 00:00:00 2001
From: Marco Brandizi <marco.brandizi@gmail.com>
Date: Tue, 15 Aug 2023 18:40:20 +0100
Subject: [PATCH] Adding CollectionUtils. Migrating to 14.0-SNAPSHOT

---
 pom.xml                                       |   2 +-
 revision-history.md                           |   6 +-
 .../utils/collections/CollectionsUtils.java   | 118 ++++++++++++++++++
 3 files changed, 123 insertions(+), 3 deletions(-)
 create mode 100644 src/main/java/uk/ac/ebi/utils/collections/CollectionsUtils.java

diff --git a/pom.xml b/pom.xml
index bc220543f..52cf68f23 100644
--- a/pom.xml
+++ b/pom.xml
@@ -4,7 +4,7 @@
 
   <groupId>uk.ac.ebi</groupId>
   <artifactId>jutils</artifactId>
-  <version>13.0.1-SNAPSHOT</version>
+  <version>14.0-SNAPSHOT</version>
   
   
   <name>JUtils - Miscellanea of Java Utils</name>
diff --git a/revision-history.md b/revision-history.md
index 260f955d0..baee7fe71 100644
--- a/revision-history.md
+++ b/revision-history.md
@@ -1,8 +1,10 @@
 # Revision History
 
-*This file was last revised on 2023-07-31*. **Please keep this note updated**.
+*This file was last revised on 2023-08-15*. **Please keep this note updated**.
 
-## 13.0.1-SNAPSHOT
+## 14.0-SNAPSHOT
+* Old classes removed
+* `CollectionsUtils` added
 
 ## 13.0
 * **These migrations are incompatible with older versions**:
diff --git a/src/main/java/uk/ac/ebi/utils/collections/CollectionsUtils.java b/src/main/java/uk/ac/ebi/utils/collections/CollectionsUtils.java
new file mode 100644
index 000000000..b96949246
--- /dev/null
+++ b/src/main/java/uk/ac/ebi/utils/collections/CollectionsUtils.java
@@ -0,0 +1,118 @@
+package uk.ac.ebi.utils.collections;
+
+import java.util.ArrayList;
+import java.util.Collection;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.Iterator;
+import java.util.List;
+import java.util.Set;
+
+/**
+ * Collections-related utils.
+ * 
+ * TODO: tests.
+ *
+ * @author brandizi
+ * <dl><dt>Date:</dt><dd>15 Aug 2023</dd></dl>
+ *
+ */
+public class CollectionsUtils
+{
+	/**
+	 * Converts the value into an immutable {@link Collection}. 
+	 * 
+	 * If the value is null, returns an {@link Collections#emptySet() empty set}.
+	 * If the value isn't a collection, returns a {@link Collections#singleton(Object) singleton set}.
+	 * If the value is already a collection, returns its 
+	 * {@link Collections#unmodifiableCollection(Collection) unmodifiable wrapper}.
+	 * 
+	 */
+	@SuppressWarnings ( "unchecked" )
+	public static <T> Collection<T> asCollection ( Object value )
+	{
+		if ( value == null ) return Collections.emptySet ();
+		
+		if ( value instanceof Collection ) 
+			return Collections.unmodifiableCollection ( (Collection<T>) value );
+		
+		return Collections.singleton ( (T) value );
+	}
+	
+	/**
+	 * Uses {@link #asCollection(Object)} to return an unmodifiable list out of the value.
+	 * 
+	 * If the result from {@link #asCollection(Object)} is a list, returns it, else 
+	 * creates a list from such result and returns an unmodifiable wrapper of it.
+	 */
+	@SuppressWarnings ( { "unchecked", "rawtypes" } )
+	public static <T> List<T> asList ( Object value )
+	{
+		var result = asCollection ( value );
+		if ( result instanceof List ) return (List<T>) result;
+		
+		return Collections.unmodifiableList ( new ArrayList ( result ) );
+	}
+	
+
+	/**
+	 * Uses {@link #asCollection(Object)} to return an unmodifiable set out of the value.
+	 * 
+	 * If the result from {@link #asCollection(Object)} is a set, returns it, else 
+	 * creates a set from such result and returns an unmodifiable wrapper of it.
+	 */
+	@SuppressWarnings ( { "unchecked", "rawtypes" } )
+	public static <T> Set<T> asSet ( Object value )
+	{
+		var result = asCollection ( value );
+		if ( result instanceof Set ) return (Set<T>) result;
+		
+		return Collections.unmodifiableSet ( new HashSet ( result ) );
+	}
+	
+	
+	/**
+	 * Converts a possibly-collection value into a singleton.
+	 * 
+	 * If the value is null, returns null.
+	 * If the value isn't a collection, returns the value unabridged.
+	 * 
+	 * If the value is a collection with one element only, returns the element
+	 * in the collection. 
+	 * 
+	 * If such collection contains more than one element, 
+	 *   if failIfMany is true, throws {@link IllegalArgumentException}
+	 *   if failIfMany is false, returns the first element in the collection value, which is then 
+	 *   undetermined
+	 */
+	@SuppressWarnings ( "unchecked" )
+	public static <T> T asValue ( Object value, boolean failIfMany )
+	{
+		if ( value == null ) return null;
+		
+		if ( ! ( value instanceof Collection ) ) return (T) value;
+			
+		// Deal with a collection
+		var coll = (Collection<T>) value;
+		
+		if ( coll.isEmpty () ) return null;
+		
+		Iterator<T> itr = coll.iterator ();
+		var result = itr.next ();
+		
+		if ( failIfMany && itr.hasNext () ) throw new IllegalArgumentException (
+			"Attempt to extract a singleton from a multi-value collection"
+		);
+		
+		return result;
+	}
+	
+	/**
+	 * Wrapper with failIfMany = false
+	 */
+	public static <T> T asValue ( Object value )
+	{
+		return asValue ( value, false );
+	}
+
+}