Add support for setting serializer/parser session properties as HTTP headers and query parameters

Author: James Bognar

juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/reflect/AnnotationInfo.java

@@ -127,6 +127,27 @@ private static int findRank(Object a) {
 		this.toString = memoize(this::findToString);
 	}
 
+	/**
+	 * Returns the annotatable object (class, method, field, etc.) where this annotation was found.
+	 *
+	 * @return The annotatable object where this annotation was found.
+	 */
+	public Annotatable getAnnotatable() {
+		return annotatable;
+	}
+
+	/**
+	 * Returns the annotatable object cast to the specified type.
+	 *
+	 * @param <A> The annotatable type.
+	 * @param type The class to cast to.
+	 * @return The annotatable element cast to the specified type.
+	 * @throws ClassCastException If the annotatable element is not of the specified type.
+	 */
+	public <A extends Annotatable> A getAnnotatable(Class<A> type) {
+		return type.cast(annotatable);
+	}
+
 	/**
 	 * Returns the annotation type of this annotation.
 	 *

juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/utils/CollectionUtils.java

@@ -129,6 +129,8 @@
 public class CollectionUtils {
 
 	// Argument name constants for assertArgNotNull
+	private static final String ARG_comparator = "comparator";
+	private static final String ARG_input = "input";
 	private static final String ARG_value = "value";
 	private static final String ARG_array = "array";
 	private static final String ARG_arrays = "arrays";
@@ -869,6 +871,26 @@ public static int[] ints(int...value) {
 		return value;
 	}
 
+	/**
+	 * Returns <jk>true</jk> if the specified collection is null or empty.
+	 *
+	 * @param c The collection to check.
+	 * @return <jk>true</jk> if the specified collection is null or empty.
+	 */
+	public static boolean isEmpty(Collection<?> c) {
+		return c == null || c.isEmpty();
+	}
+
+	/**
+	 * Returns <jk>true</jk> if the specified map is null or empty.
+	 *
+	 * @param m The map to check.
+	 * @return <jk>true</jk> if the specified map is null or empty.
+	 */
+	public static boolean isEmpty(Map<?,?> m) {
+		return m == null || m.isEmpty();
+	}
+
 	/**
 	 * Returns <jk>true</jk> if the specified array is null or has a length of zero.
 	 *
@@ -2015,6 +2037,64 @@ public static <T> Stream<T> rstream(List<T> value) {
 		return IntStream.range(0, value.size()).mapToObj(i -> value.get(value.size() - 1 - i));
 	}
 
+	/**
+	 * Removes negation tokens from a list.
+	 *
+	 * <p>
+	 * A negation token is a string starting with <js>'-'</js> followed by at least one character.
+	 * When encountered, it removes the first prior occurrence of the corresponding positive token.
+	 *
+	 * <h5 class='section'>Example:</h5>
+	 * <p class='bjava'>
+	 * 	List&lt;String&gt; <jv>result</jv> = <jsm>removeNegations</jsm>(list(<js>"a"</js>, <js>"b"</js>, <js>"-a"</js>, <js>"c"</js>));
+	 * 	<jc>// Produces: ["b", "c"]</jc>
+	 * </p>
+	 *
+	 * @param input The input list. Cannot be <jk>null</jk>.
+	 * @return The list with negation tokens applied, or the original list if no negation tokens were present.
+	 */
+	public static List<String> removeNegations(List<String> input) {
+		assertArgNotNull(ARG_input, input);
+		var hasNegation = false;
+		for (var token : input) {
+			if (token != null && token.length() > 1 && token.charAt(0) == '-') {
+				hasNegation = true;
+				break;
+			}
+		}
+		if (!hasNegation)
+			return input;
+		var out = new ArrayList<String>(input.size());
+		for (var token : input) {
+			if (token != null && token.length() > 1 && token.charAt(0) == '-')
+				out.remove(token.substring(1));
+			else
+				out.add(token);
+		}
+		return out;
+	}
+
+	/**
+	 * Creates a {@link TreeSet} with a custom comparator from a collection of elements.
+	 *
+	 * <p>
+	 * Null elements in the collection are silently skipped.
+	 *
+	 * @param <E> The element type.
+	 * @param comparator The comparator to use for ordering. Cannot be <jk>null</jk>.
+	 * @param elements The initial elements. Can be <jk>null</jk> (treated as empty).
+	 * @return A new {@link TreeSet} containing all non-null elements from the collection.
+	 */
+	public static <E> SortedSet<E> treeSet(Comparator<? super E> comparator, Collection<? extends E> elements) {
+		assertArgNotNull(ARG_comparator, comparator);
+		var s = new TreeSet<E>(comparator);
+		if (elements != null)
+			for (var e : elements)
+				if (e != null)
+					s.add(e);
+		return s;
+	}
+
 	/**
 	 * Shortcut for creating a modifiable set out of an array of values.
 	 *

juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/utils/StringUtils.java

@@ -77,6 +77,9 @@ public class StringUtils {
 	/** Zero-length string constant. */
 	public static final String EMPTY = "";
 
+	/** Zero-length string array constant. */
+	public static final String[] EMPTY_STRING_ARRAY = new String[0];
+
 	/** Characters allowed at the beginning of a numeric literal. */
 	public static final AsciiSet FIRST_NUMBER_CHARS = AsciiSet.of("+-.#0123456789");
 

juneau-rest/juneau-rest-client/src/main/java/org/apache/juneau/rest/client/RestClient.java

@@ -29,6 +29,7 @@
 import static org.apache.juneau.http.HttpMethod.*;
 import static org.apache.juneau.http.HttpParts.*;
 import static org.apache.juneau.httppart.HttpPartType.*;
+import static org.apache.juneau.rest.RestSharedConstants.*;
 import static org.apache.juneau.rest.client.RestOperation.*;
 
 import java.io.*;
@@ -2552,6 +2553,72 @@ public Builder headersDefault(Header...parts) {
 			return this;
 		}
 
+		/**
+		 * Sets a default request header with serializer session options (JSON5 map) for all requests.
+		 *
+		 * <p>
+		 * This is a shortcut for <c>headersDefault(basicHeader({@link org.apache.juneau.rest.RestSharedConstants#HEADER_JuneauSerializerOptions}, <jv>json5</jv>))</c>.
+		 *
+		 * @param json5
+		 * 	Serializer session options in JSON5 form.
+		 * 	<br>Can be <jk>null</jk> (default is not set by this method).
+		 * @return This object.
+		 */
+		public Builder serializerSessionOptionsHeader(String json5) {
+			if (json5 != null)
+				headersDefault(basicHeader(HEADER_JuneauSerializerOptions, json5));
+			return this;
+		}
+
+		/**
+		 * Sets a default request header with parser session options (JSON5 map) for all requests.
+		 *
+		 * <p>
+		 * This is a shortcut for <c>headersDefault(basicHeader({@link org.apache.juneau.rest.RestSharedConstants#HEADER_JuneauParserOptions}, <jv>json5</jv>))</c>.
+		 *
+		 * @param json5
+		 * 	Parser session options in JSON5 form.
+		 * 	<br>Can be <jk>null</jk> (default is not set by this method).
+		 * @return This object.
+		 */
+		public Builder parserSessionOptionsHeader(String json5) {
+			if (json5 != null)
+				headersDefault(basicHeader(HEADER_JuneauParserOptions, json5));
+			return this;
+		}
+
+		/**
+		 * Convenience for {@link #serializerSessionOptionsHeader(String)} using a map serialized with JSON5.
+		 *
+		 * @param properties
+		 * 	Property names and values for serializer session options.
+		 * 	<br>Can be <jk>null</jk> (treated as an empty map).
+		 * @return This object.
+		 */
+		public Builder serializerSessionOptionsHeader(Map<String,?> properties) {
+			try {
+				return serializerSessionOptionsHeader(isEmpty(properties) ? null : Json5.of(properties));
+			} catch (SerializeException e) {
+				throw rex(e, "Could not serialize serializer session options header");
+			}
+		}
+
+		/**
+		 * Convenience for {@link #parserSessionOptionsHeader(String)} using a map serialized with JSON5.
+		 *
+		 * @param properties
+		 * 	Property names and values for parser session options.
+		 * 	<br>Can be <jk>null</jk> (treated as an empty map).
+		 * @return This object.
+		 */
+		public Builder parserSessionOptionsHeader(Map<String,?> properties) {
+			try {
+				return parserSessionOptionsHeader(isEmpty(properties) ? null : Json5.of(properties));
+			} catch (SerializeException e) {
+				throw rex(e, "Could not serialize parser session options header");
+			}
+		}
+
 		/**
 		 * Convenience method for specifying HTML as the marshalling transmission media type.
 		 *
@@ -4639,6 +4706,72 @@ public Builder queryDataDefault(NameValuePair...parts) {
 			return this;
 		}
 
+		/**
+		 * Sets a default query parameter with serializer session options (UON map) for all requests.
+		 *
+		 * <p>
+		 * This is a shortcut for <c>queryDataDefault(stringPart({@link org.apache.juneau.rest.RestSharedConstants#QUERY_juneauSerializerOptions}, <jv>uon</jv>))</c>.
+		 *
+		 * @param uon
+		 * 	Serializer session options in UON form.
+		 * 	<br>Can be <jk>null</jk> (default is not set by this method).
+		 * @return This object.
+		 */
+		public Builder serializerSessionOptionsQueryDefault(String uon) {
+			if (uon != null)
+				queryDataDefault(stringPart(QUERY_juneauSerializerOptions, uon));
+			return this;
+		}
+
+		/**
+		 * Sets a default query parameter with parser session options (UON map) for all requests.
+		 *
+		 * <p>
+		 * This is a shortcut for <c>queryDataDefault(stringPart({@link org.apache.juneau.rest.RestSharedConstants#QUERY_juneauParserOptions}, <jv>uon</jv>))</c>.
+		 *
+		 * @param uon
+		 * 	Parser session options in UON form.
+		 * 	<br>Can be <jk>null</jk> (default is not set by this method).
+		 * @return This object.
+		 */
+		public Builder parserSessionOptionsQueryDefault(String uon) {
+			if (uon != null)
+				queryDataDefault(stringPart(QUERY_juneauParserOptions, uon));
+			return this;
+		}
+
+		/**
+		 * Convenience for {@link #serializerSessionOptionsQueryDefault(String)} using {@link org.apache.juneau.marshaller.Uon#of(Object)}.
+		 *
+		 * @param properties
+		 * 	Property names and values for serializer session options.
+		 * 	<br>Can be <jk>null</jk> (treated as an empty map).
+		 * @return This object.
+		 */
+		public Builder serializerSessionOptionsQueryDefault(Map<String,?> properties) {
+			try {
+				return serializerSessionOptionsQueryDefault(isEmpty(properties) ? null : Uon.of(properties));
+			} catch (SerializeException e) {
+				throw rex(e, "Could not serialize serializer session options query default");
+			}
+		}
+
+		/**
+		 * Convenience for {@link #parserSessionOptionsQueryDefault(String)} using {@link org.apache.juneau.marshaller.Uon#of(Object)}.
+		 *
+		 * @param properties
+		 * 	Property names and values for parser session options.
+		 * 	<br>Can be <jk>null</jk> (treated as an empty map).
+		 * @return This object.
+		 */
+		public Builder parserSessionOptionsQueryDefault(Map<String,?> properties) {
+			try {
+				return parserSessionOptionsQueryDefault(isEmpty(properties) ? null : Uon.of(properties));
+			} catch (SerializeException e) {
+				throw rex(e, "Could not serialize parser session options query default");
+			}
+		}
+
 		/**
 		 * <i><l>WriterSerializer</l> configuration property:&emsp;</i>  Quote character.
 		 *