11/*
2- * Copyright (c) 2019-2023 Tada AB and other contributors, as listed below.
2+ * Copyright (c) 2019-2024 Tada AB and other contributors, as listed below.
33 *
44 * All rights reserved. This program and the accompanying materials
55 * are made available under the terms of the The BSD 3-Clause License
@@ -147,16 +147,34 @@ private XML() { } // no instances
147147 * {@link Exception#getSuppressed getSuppressed}. The return is
148148 * immediate, without any remaining names being tried, if an exception
149149 * is caught that is not assignable to a class in the
150- * <var>expected</var> list. Such an exception will be passed to the
151- * <var>onUnexpected</var> handler if that is non-null; otherwise,
152- * it will be returned (or added to the suppressed list of the
153- * exception to be returned) just as expected exceptions are.
150+ * <var>expected</var> list. Such an exception is returned (or added to
151+ * the suppressed list of an exception already to be returned) only if
152+ * the <var>onUnexpected</var> handler is null; otherwise, it is passed
153+ * to the handler and does not affect the method's return.
154+ *<p>
155+ * For some purposes, a single call of this method may not suffice: if
156+ * alternate means to establish a desired configuration have existed and
157+ * are not simply alternate property names that will accept the same
158+ * value. For such a case, this method may be called more than once. The
159+ * caller abandons the sequence of calls after the first call that
160+ * returns null (indicating that it either succeeded, or incurred an
161+ * unexpected exception and passed it to the <var>onUnexpected</var>
162+ * handler. Otherwise, the exception returned by the first call can be
163+ * passed as <var>caught</var> to the next call, instead of passing the
164+ * usual null. (When a non-null <var>caught</var> is passed, it will be
165+ * returned on failure, even if an unexpected exception has been caught;
166+ * therefore, should it ever be necessary to chain more than two of
167+ * these calls, the caller should abandon the sequence as soon as a call
168+ * returns null <em>or</em> returns its <var>caught</var> argument with
169+ * no growth of its suppressed list.)
154170 * @param setter typically a method reference for a method that
155171 * takes a string key and some value.
156172 * @param value the value to pass to the setter
157173 * @param expected a list of exception classes that can be foreseen
158174 * to indicate that a key was not recognized, and the operation
159175 * should be retried with the next possible key.
176+ * @param caught null, or an exception returned by a preceding call if
177+ * an operation cannot be implemented with one call of this method
160178 * @param onUnexpected invoked, if non-null, on an {@code Exception}
161179 * that is caught and matches nothing in the expected list, instead
162180 * of returning it. If this parameter is null, such an exception is
@@ -165,16 +183,19 @@ private XML() { } // no instances
165183 * immediate, without trying remaining names, if any.
166184 * @param names one or more String keys to be tried in order until
167185 * the action succeeds.
168- * @return null if any attempt succeeded, otherwise an exception,
169- * which may have further exceptions in its suppressed list.
186+ * @return null if any attempt succeeded, or if the first exception
187+ * caught was passed to the onUnexpected handler; otherwise the first
188+ * exception caught (if the caller supplied a non-null
189+ * <var>caught</var>, then that exception), which may have further
190+ * exceptions in its suppressed list.
170191 */
171192 public static <T , V extends T > Exception setFirstSupported (
172193 SetMethod <? super T > setter , V value ,
173194 List <Class <? extends Exception >> expected ,
195+ Exception caught ,
174196 Consumer <? super Exception > onUnexpected , String ... names )
175197 {
176198 requireNonNull (expected );
177- Exception caught = null ;
178199 for ( String name : names )
179200 {
180201 try
@@ -204,6 +225,18 @@ public static <T, V extends T> Exception setFirstSupported(
204225 return caught ;
205226 }
206227
228+ /**
229+ * Calls the six-argument overload passing null for <var>caught</var>.
230+ */
231+ public static <T , V extends T > Exception setFirstSupported (
232+ SetMethod <? super T > setter , V value ,
233+ List <Class <? extends Exception >> expected ,
234+ Consumer <? super Exception > onUnexpected , String ... names )
235+ {
236+ return setFirstSupported (
237+ setter , value , expected , null , onUnexpected , names );
238+ }
239+
207240 /**
208241 * A functional interface fitting various {@code setFeature} or
209242 * {@code setProperty} methods in Java XML APIs.
@@ -268,6 +301,17 @@ public interface Parsing<T extends Parsing<T>>
268301 /** Whether to allow a DTD at all. */
269302 T allowDTD (boolean v );
270303
304+ /**
305+ * Specifies that any DTD should be ignored (neither processed nor
306+ * rejected as an error).
307+ *<p>
308+ * This treatment is available in Java 22 and later.
309+ * In earlier Java versions, this will not succeed. Where it is
310+ * supported, the most recent call of this method or of
311+ * {@link #allowDTD allowDTD} will be honored.
312+ */
313+ T ignoreDTD ();
314+
271315 /**
272316 * Whether to retrieve external "general" entities (those
273317 * that can be used in the document body) declared in the DTD.
0 commit comments