This is an automated email from the ASF dual-hosted git repository.
ppkarwasz pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/commons-xml.git
The following commit(s) were added to refs/heads/main by this push:
new cf99324 Add trailing newlines, use American spelling, and spell out
Latin abbreviations (#19)
cf99324 is described below
commit cf99324bc2af7d91e2a4ffb950b39659297d9d27
Author: Piotr P. Karwasz <[email protected]>
AuthorDate: Wed Jul 8 23:04:12 2026 +0200
Add trailing newlines, use American spelling, and spell out Latin
abbreviations (#19)
* Add trailing newlines and use American spelling
Add the missing EOL at end of file to the three .github config files,
and convert British spellings (Honoured, flavour(s), synchronise,
standardised, defence) to American in Javadoc, comments, and docs.
* Replace Latin abbreviations with English phrases
Spell out e.g. as "for example", i.e. as "that is", and etc. as
"and so on" in Javadoc and comments. Leaves the upstream
CONTRIBUTING.md boilerplate and the spotbugs URL path untouched.
---
.github/dependabot.yml | 2 +-
.github/workflows/codeql-analysis.yml | 2 +-
.github/workflows/maven.yml | 2 +-
.../apache/commons/xml/DocumentBuilderHardener.java | 2 +-
src/main/java/org/apache/commons/xml/Limits.java | 2 +-
.../org/apache/commons/xml/SAXParserHardener.java | 2 +-
.../java/org/apache/commons/xml/XmlFactories.java | 2 +-
src/site/markdown/index.md | 4 ++--
.../org/apache/commons/xml/AttackTestSupport.java | 20 ++++++++++----------
.../org/apache/commons/xml/BillionLaughsTest.java | 2 +-
.../java/org/apache/commons/xml/NoDoctypeTest.java | 2 +-
.../java11/org/apache/commons/xml/DescriptorIT.java | 4 ++--
12 files changed, 23 insertions(+), 23 deletions(-)
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 7125dd4..cc8ef12 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -25,4 +25,4 @@ updates:
schedule:
interval: "weekly"
cooldown:
- default-days: 7
\ No newline at end of file
+ default-days: 7
diff --git a/.github/workflows/codeql-analysis.yml
b/.github/workflows/codeql-analysis.yml
index fff0865..68247ef 100644
--- a/.github/workflows/codeql-analysis.yml
+++ b/.github/workflows/codeql-analysis.yml
@@ -32,4 +32,4 @@ jobs:
permissions:
actions: read
contents: read
- security-events: write
\ No newline at end of file
+ security-events: write
diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml
index 1687801..21f86f6 100644
--- a/.github/workflows/maven.yml
+++ b/.github/workflows/maven.yml
@@ -198,4 +198,4 @@ jobs:
android-tests/build/outputs/androidTest-results/
android-tests/build/reports/androidTests/
if-no-files-found: ignore
- retention-days: 14
\ No newline at end of file
+ retention-days: 14
diff --git a/src/main/java/org/apache/commons/xml/DocumentBuilderHardener.java
b/src/main/java/org/apache/commons/xml/DocumentBuilderHardener.java
index 9aba89f..92100a0 100644
--- a/src/main/java/org/apache/commons/xml/DocumentBuilderHardener.java
+++ b/src/main/java/org/apache/commons/xml/DocumentBuilderHardener.java
@@ -67,7 +67,7 @@ static DocumentBuilderFactory harden(final
DocumentBuilderFactory factory) {
// ACCESS_EXTERNAL_* support is the dividing capability between JAXP
1.5 implementations and older ones.
if (trySetAttribute(factory, XMLConstants.ACCESS_EXTERNAL_DTD, "")
&& trySetAttribute(factory,
XMLConstants.ACCESS_EXTERNAL_SCHEMA, "")) {
- // Honoured: the JAXP 1.5 properties block external fetches, so
the bare factory is already hardened.
+ // Honored: the JAXP 1.5 properties block external fetches, so the
bare factory is already hardened.
return factory;
}
// Rejected: external Xerces ignores ACCESS_EXTERNAL_*; install a
deny-all resolver on every DocumentBuilder.
diff --git a/src/main/java/org/apache/commons/xml/Limits.java
b/src/main/java/org/apache/commons/xml/Limits.java
index ec00834..4829711 100644
--- a/src/main/java/org/apache/commons/xml/Limits.java
+++ b/src/main/java/org/apache/commons/xml/Limits.java
@@ -97,7 +97,7 @@ final class Limits {
*/
private static final int DEFAULT_MAX_ELEMENT_DEPTH = 100;
/**
- * Maximum length, in characters, of an XML name (element name, attribute
name, namespace prefix, etc); JDK 25 secure value.
+ * Maximum length, in characters, of an XML name (element name, attribute
name, namespace prefix, and so on); JDK 25 secure value.
*
* <p>Override with system property {@value #SP_MAX_NAME_LIMIT}.</p>
*
diff --git a/src/main/java/org/apache/commons/xml/SAXParserHardener.java
b/src/main/java/org/apache/commons/xml/SAXParserHardener.java
index 47e952e..708b989 100644
--- a/src/main/java/org/apache/commons/xml/SAXParserHardener.java
+++ b/src/main/java/org/apache/commons/xml/SAXParserHardener.java
@@ -158,7 +158,7 @@ static SAXParserFactory harden(final SAXParserFactory
factory) {
*/
static XMLReader hardenReader(final XMLReader reader) {
if (reader instanceof HardeningXMLReader) {
- // Already hardened (e.g. handed back through
XmlFactories.harden(XMLReader)); the floor is already in place.
+ // Already hardened (for example, handed back through
XmlFactories.harden(XMLReader)); the floor is already in place.
return reader;
}
if (ANDROID_EXPAT_READER.equals(reader.getClass().getName())) {
diff --git a/src/main/java/org/apache/commons/xml/XmlFactories.java
b/src/main/java/org/apache/commons/xml/XmlFactories.java
index 41056ff..a5b5c6d 100644
--- a/src/main/java/org/apache/commons/xml/XmlFactories.java
+++ b/src/main/java/org/apache/commons/xml/XmlFactories.java
@@ -67,7 +67,7 @@
* <h2>Thread safety</h2>
*
* <p>The returned factories inherit the thread-safety properties of the
underlying JAXP implementation, which in practice means they are <strong>not
- * guaranteed to be thread-safe</strong>. Create a new factory per thread or
synchronise externally.</p>
+ * guaranteed to be thread-safe</strong>. Create a new factory per thread or
synchronize externally.</p>
*
* <p>This class itself is thread-safe: all methods are static and
stateless.</p>
*/
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index daa877b..98cc59e 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -30,7 +30,7 @@ stock JDK and external JAXP implementations.
Any Java library that parses XML has to harden JAXP before handing a factory
to user code, and every library ends up
copy-pasting the same hardening snippet. The snippet is fragile: the
attributes and features needed to harden a factory
-are not standardised, each JAXP implementation exposes a slightly different
set, and setting an unknown one throws an
+are not standardized, each JAXP implementation exposes a slightly different
set, and setting an unknown one throws an
exception that callers routinely swallow. Writing this block correctly for
every implementation is real work, and
duplicating it across projects means every project owns the maintenance burden
on its own.
@@ -142,5 +142,5 @@ pass the result as a `DOMSource` or `SAXSource`.
There is no caching or pooling inside `XmlFactories`; callers on a hot path
are responsible for their own caching. The
returned factories inherit the thread-safety properties of the underlying JAXP
implementation, which in practice means
-they are not thread-safe. Create a new factory per thread or synchronise
externally.
+they are not thread-safe. Create a new factory per thread or synchronize
externally.
diff --git a/src/test/java/org/apache/commons/xml/AttackTestSupport.java
b/src/test/java/org/apache/commons/xml/AttackTestSupport.java
index 952cd75..c0ebd67 100644
--- a/src/test/java/org/apache/commons/xml/AttackTestSupport.java
+++ b/src/test/java/org/apache/commons/xml/AttackTestSupport.java
@@ -58,17 +58,17 @@
/**
* Shared fixtures for attack tests.
*
- * <p>The hardened-side helpers come in three flavours, distinguished by their
suffix:</p>
+ * <p>The hardened-side helpers come in three flavors, distinguished by their
suffix:</p>
*
* <ul>
* <li>{@code assert*Blocks(...)} runs the payload through a hardened
factory from {@link XmlFactories} and asserts the parse throws. Used when the
hardening
* layer is expected to reject the attack outright.</li>
* <li>{@code assert*DoesNotLeak(...)} runs the payload through a hardened
factory and asserts the parse completes without throwing and without producing
the
- * {@link #LEAKED_MARKER} string. Used when the hardening contract
guarantees the parse succeeds but never resolves the external resource (e.g.
+ * {@link #LEAKED_MARKER} string. Used when the hardening contract
guarantees the parse succeeds but never resolves the external resource (for
example,
* {@code XERCES_LOAD_EXTERNAL_DTD=false} silently skipping the external
subset, with the body's undeclared entity reference dropped per XML 1.0
* §4.1).</li>
* <li>{@code assert*BlocksOrDoesNotLeak(...)} accepts either of the
previous two outcomes. Used where the same hardening contract surfaces
differently across
- * providers (e.g. stock-JDK XSLTC throws via {@code
ACCESS_EXTERNAL_DTD} while Apache Xalan silently skips because its
source-rewrite routes parsing
+ * providers (for example, stock-JDK XSLTC throws via {@code
ACCESS_EXTERNAL_DTD} while Apache Xalan silently skips because its
source-rewrite routes parsing
* through a {@code XERCES_LOAD_EXTERNAL_DTD=false} reader).</li>
* </ul>
*
@@ -189,7 +189,7 @@ static void assertDomBlocks(final String payload) {
* Asserts a hardened DOM parse completes without throwing and without
leaked content.
*
* <p>{@link DocumentBuilder#parse(InputSource)} via {@link
XmlFactories#newDocumentBuilderFactory()}; use this when the hardening
guarantee is "the parse
- * succeeds but never resolves the external resource", e.g. when {@code
XERCES_LOAD_EXTERNAL_DTD=false} silently skips the external subset.</p>
+ * succeeds but never resolves the external resource", for example, when
{@code XERCES_LOAD_EXTERNAL_DTD=false} silently skips the external subset.</p>
*/
static void assertDomDoesNotLeak(final String payload) {
assertNoLeakStrict(() -> domParseAndCaptureText(payload), "DOM");
@@ -208,7 +208,7 @@ static void assertDomParses(final String payload) {
* Skeleton for every {@code assert*BlocksOrDoesNotLeak} helper.
*
* <p>Treats a thrown exception of one of the {@code expected} types as
"hardening blocked at parse" (acceptable); otherwise asserts the captured output
- * omits {@link #LEAKED_MARKER}. A throw whose type does not match {@code
expected} fails the test, so unrelated failures (e.g. a {@link
HardeningException}
+ * omits {@link #LEAKED_MARKER}. A throw whose type does not match {@code
expected} fails the test, so unrelated failures (for example, a {@link
HardeningException}
* because no recipe matched the JAXP implementation) cannot be silently
accepted as a clean block.</p>
*
* @param action the parse to execute, returning the captured output
text checked for {@link #LEAKED_MARKER}.
@@ -409,7 +409,7 @@ static void assertSaxBlocks(final String payload) {
* Asserts a hardened SAX parse completes without throwing and without
leaked content.
*
* <p>{@link XMLReader#parse(InputSource)} on a parser from {@link
XmlFactories#newSAXParserFactory()}; use this when the hardening guarantee is
"the parse
- * succeeds but never resolves the external resource", e.g. when {@code
XERCES_LOAD_EXTERNAL_DTD=false} silently skips the external subset.</p>
+ * succeeds but never resolves the external resource", for example, when
{@code XERCES_LOAD_EXTERNAL_DTD=false} silently skips the external subset.</p>
*/
static void assertSaxDoesNotLeak(final String payload) {
assertNoLeakStrict(() ->
captureCharacters(strictXMLReader(XmlFactories.newSAXParserFactory()),
payload), "SAX");
@@ -446,7 +446,7 @@ static void assertSchemaCompiles(final Source xsd) {
* Asserts a hardened Schema compilation completes without throwing.
*
* <p>{@link SchemaFactory#newSchema(Source)} via {@link
XmlFactories#newSchemaFactory()}; use this when the hardening contract
guarantees the compile
- * succeeds but never resolves the external resource (e.g. {@code
XERCES_LOAD_EXTERNAL_DTD=false} silently skipping the external subset, with the
body's
+ * succeeds but never resolves the external resource (for example, {@code
XERCES_LOAD_EXTERNAL_DTD=false} silently skipping the external subset, with the
body's
* undeclared entity reference dropped per XML 1.0 §4.1).</p>
*/
static void assertSchemaDoesNotLeak(final Source xsd) {
@@ -456,7 +456,7 @@ static void assertSchemaDoesNotLeak(final Source xsd) {
/**
* Asserts a hardened StAX parse of the payload throws.
*
- * <p>{@link XMLStreamReader} and {@link XMLEventReader} from {@link
XmlFactories#newXMLInputFactory()}; both flavours are exercised and either must
+ * <p>{@link XMLStreamReader} and {@link XMLEventReader} from {@link
XmlFactories#newXMLInputFactory()}; both flavors are exercised and either must
* throw.</p>
*/
static void assertStaxBlocks(final String payload) {
@@ -467,8 +467,8 @@ static void assertStaxBlocks(final String payload) {
/**
* Asserts a hardened StAX parse completes without throwing and without
leaked content.
*
- * <p>{@link XMLStreamReader} and {@link XMLEventReader} from {@link
XmlFactories#newXMLInputFactory()}; both flavours are exercised. Use this when
the
- * hardening guarantee is "the parse succeeds but never resolves the
external resource", e.g. when the JDK's {@code ignore-external-dtd} property
silently
+ * <p>{@link XMLStreamReader} and {@link XMLEventReader} from {@link
XmlFactories#newXMLInputFactory()}; both flavors are exercised. Use this when
the
+ * hardening guarantee is "the parse succeeds but never resolves the
external resource", for example, when the JDK's {@code ignore-external-dtd}
property silently
* skips the external subset.</p>
*/
static void assertStaxDoesNotLeak(final String payload) {
diff --git a/src/test/java/org/apache/commons/xml/BillionLaughsTest.java
b/src/test/java/org/apache/commons/xml/BillionLaughsTest.java
index eb18e72..164839a 100644
--- a/src/test/java/org/apache/commons/xml/BillionLaughsTest.java
+++ b/src/test/java/org/apache/commons/xml/BillionLaughsTest.java
@@ -45,7 +45,7 @@
* <p>Which fixture each test uses:</p>
*
* <ul>
- * <li>{@code hardened*} tests pull from {@code hardened*Payload} helpers:
large fixture on Android (libexpat is the only defence), medium fixture on JDK
+ * <li>{@code hardened*} tests pull from {@code hardened*Payload} helpers:
large fixture on Android (libexpat is the only defense), medium fixture on JDK
* (entity-expansion count limit is sufficient).</li>
* <li>{@code unconfigured*} positive controls pull from {@code
medium*Payload} helpers regardless of platform: libexpat's billion-laughs check
cannot be
* disabled from Java, so a permissive parse of the large fixture would
still trip on Android.</li>
diff --git a/src/test/java/org/apache/commons/xml/NoDoctypeTest.java
b/src/test/java/org/apache/commons/xml/NoDoctypeTest.java
index a6536e0..e95335b 100644
--- a/src/test/java/org/apache/commons/xml/NoDoctypeTest.java
+++ b/src/test/java/org/apache/commons/xml/NoDoctypeTest.java
@@ -24,7 +24,7 @@
* Checks that a plain document without a {@code DOCTYPE} declaration parses
cleanly through every hardened JAXP surface.
*
* <p>This is the realistic 99% case for hardened input; the hardening
contract being verified is "documents without a DOCTYPE parse cleanly through
every
- * JAXP surface" so accidental tightening (e.g. a resolver that refuses the
synthetic-external-subset hook) is caught.</p>
+ * JAXP surface" so accidental tightening (for example, a resolver that
refuses the synthetic-external-subset hook) is caught.</p>
*/
class NoDoctypeTest {
diff --git a/src/test/java11/org/apache/commons/xml/DescriptorIT.java
b/src/test/java11/org/apache/commons/xml/DescriptorIT.java
index f275018..28a1c96 100644
--- a/src/test/java11/org/apache/commons/xml/DescriptorIT.java
+++ b/src/test/java11/org/apache/commons/xml/DescriptorIT.java
@@ -118,7 +118,7 @@ private static JarEntry findModuleInfo(final JarFile jar) {
}
/**
- * Returns whether {@code pkg} is exported by an OSGi system bundle, i.e.
it sits under one of {@link #PLATFORM_PACKAGE_PREFIXES}.
+ * Returns whether {@code pkg} is exported by an OSGi system bundle, that
is, it sits under one of {@link #PLATFORM_PACKAGE_PREFIXES}.
*/
private static boolean isPlatformPackage(final String pkg) {
for (final String prefix : PLATFORM_PACKAGE_PREFIXES) {
@@ -150,7 +150,7 @@ private static List<String> splitClauses(final String
header) {
}
/**
- * Returns the package name of a clause, i.e. everything before its first
{@code ;} attribute separator.
+ * Returns the package name of a clause, that is, everything before its
first {@code ;} attribute separator.
*/
private static String packageName(final String clause) {
final int semicolon = clause.indexOf(';');
