This is an automated email from the ASF dual-hosted git repository.
garydgregory pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/commons-secure-xml.git
The following commit(s) were added to refs/heads/main by this push:
new df281a7 Site documentation and comments.
df281a7 is described below
commit df281a78fe64989c60ab05920f0794a1b71db7c8
Author: Gary Gregory <[email protected]>
AuthorDate: Tue Sep 15 07:33:08 2026 -0700
Site documentation and comments.
---
CONTRIBUTING.md | 4 ++--
android-tests/README.md | 2 +-
src/conf/maven-pmd-plugin.xml | 2 +-
src/main/javadoc/overview.html | 17 ++++++++---------
src/site/markdown/threat_model.md | 10 +++++-----
5 files changed, 17 insertions(+), 18 deletions(-)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 809059c..9016a98 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -42,13 +42,13 @@ Contributing to Apache Commons Secure XML
======================
Have you found a bug, or do you have an idea for a cool new feature?
Contributing code is a great way to give something back to the open-source
community.
-Before you dig right into the code, we need contributors to follow a few
guidelines to have a chance of keeping on top of things.
+Before you dig right into the code, please review these guidelines to help us
manage contributions.
Getting Started
---------------
+ Make sure you have a [JIRA account](https://issues.apache.org/jira/).
-+ Make sure you have a [GitHub account](https://github.com/signup/free). This
is not essential, but makes providing patches much easier.
++ Make sure you have a [GitHub account](https://github.com/signup/free). This
is not essential, but it makes providing patches much easier.
+ If you're planning to implement a new feature, it makes sense to discuss
your changes on the [dev list](https://commons.apache.org/mail-lists.html)
first. This way you can make sure you're not wasting your time on something
that isn't considered to be in Apache Commons Secure XML's scope.
+ Submit a [Jira Ticket][jira] for your issue, assuming one does not already
exist.
+ Clearly describe the issue, including steps to reproduce it if it is a bug.
diff --git a/android-tests/README.md b/android-tests/README.md
index 4c0936c..bb2f15d 100644
--- a/android-tests/README.md
+++ b/android-tests/README.md
@@ -17,7 +17,7 @@ limitations under the License.
# Android instrumented tests
-Runs the attack-test suite from `../src/test/java` against the Android
runtime, exercising
+This module runs the attack-test suite from `../src/test/java` against the
Android runtime, exercising
the Harmony-based DOM and SAX factories that ship with Android. The Maven
build does not include this
module; it is a standalone Gradle build kept separate so the default `mvn`
goal stays JVM-only.
diff --git a/src/conf/maven-pmd-plugin.xml b/src/conf/maven-pmd-plugin.xml
index cc08fdf..7ac40d9 100644
--- a/src/conf/maven-pmd-plugin.xml
+++ b/src/conf/maven-pmd-plugin.xml
@@ -22,7 +22,7 @@ under the License.
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance";
xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0
https://pmd.sourceforge.net/ruleset_2_0_0.xsd";>
<description>
- The default ruleset used by the Maven PMD Plugin, when no other
ruleset is specified.
+ The default ruleset used by the Maven PMD Plugin when no other ruleset
is specified.
It contains the rules of the old (pre PMD 6.0.0) rulesets java-basic,
java-empty, java-imports,
java-unnecessary, and java-unusedcode.
diff --git a/src/main/javadoc/overview.html b/src/main/javadoc/overview.html
index 7c08487..ede6236 100644
--- a/src/main/javadoc/overview.html
+++ b/src/main/javadoc/overview.html
@@ -132,7 +132,7 @@ <h2>Supported Implementations</h2>
</p>
<p>
<strong>DOM Parsing</strong> via
- <code>{@link
org.apache.commons.xml.secure.SecureDocumentBuilderFactory}</code>;
+ <code>{@link
org.apache.commons.xml.secure.SecureDocumentBuilderFactory}</code>:
</p>
<div class="sourceCode" id="cb1">
<pre class="sourceCode java">
@@ -146,7 +146,7 @@ <h2>Supported Implementations</h2>
</div>
<p>
<strong>SAX Parsing</strong> via
- <code>{@link
org.apache.commons.xml.secure.SecureSAXParserFactory}</code>;
+ <code>{@link
org.apache.commons.xml.secure.SecureSAXParserFactory}</code>:
</p>
<div class="sourceCode" id="cb2">
<pre class="sourceCode java">
@@ -282,9 +282,8 @@ <h2>Stylesheets and Schemas</h2>
parser and pass the result as a
<a
href="https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/javax/xml/transform/dom/DOMSource.html";><code>DOMSource</code></a>
or
- <a
href="https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/javax/xml/transform/sax/SAXSource.html";><code>SAXSource</code></a>
- . A stylesheet also chooses where the transform writes (
- <code>xsl:result-document</code>):
+ <a
href="https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/javax/xml/transform/sax/SAXSource.html";><code>SAXSource</code></a>.
+ A stylesheet also chooses where the transform writes
(<code>xsl:result-document</code>):
the securing governs reads only, so restrict output destinations
yourself when running an untrusted stylesheet (see the <a
href="../threat_model.html">Threat
Model</a>).
</p>
@@ -311,7 +310,7 @@ <h2>Transformer Handlers and Filters</h2>
</p>
</section>
<section id="caching-and-thread-safety">
- <h2>Caching and Thread-Safety</h2>
+ <h2>Caching and Thread Safety</h2>
<p>
There is no caching or pooling inside
<code>org.apache.commons.xml.secure</code>;
@@ -391,7 +390,7 @@ <h2>Resolvers</h2>
The <code>type</code> argument tells them apart, as DOM Level 3 Load
and Save prescribes:
<a
href="https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/javax/xml/XMLConstants.html#W3C_XML_SCHEMA_NS_URI";><code>XMLConstants.W3C_XML_SCHEMA_NS_URI</code></a>
for a schema document,
<a
href="https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/javax/xml/XMLConstants.html#XML_DTD_NS_URI";><code>XMLConstants.XML_DTD_NS_URI</code></a>
for a DTD or an entity.
- A schema references its neighbors relatively, so resolve the system
identifier against the base URI before matching it.
+ A schema references its neighbors using relative URIs, so resolve the
system identifier against the base URI before matching it.
</p>
<div class="sourceCode" id="cb8">
<pre class="sourceCode java">
@@ -428,10 +427,10 @@ <h2>Resolvers</h2>
(<code>xsl:include</code> and <code>xsl:import</code>)
and for everything the transform fetches as it runs:
<code>document()</code>,
- and on an XSLT 3.0 implementation the <code>unparsed-text()</code>
family and <code>json-doc()</code> as well.
+ and on an XSLT 3.0 implementation, the <code>unparsed-text()</code>
family and <code>json-doc()</code> as well.
A <a
href="https://docs.oracle.com/en/java/javase/25/docs/api/java.xml/javax/xml/transform/stream/StreamSource.html";><code>StreamSource</code></a>
you return is re-parsed with a secured reader,
so the references inside the resource you allowed face the same floor
again.
- A function that cannot accept an empty document in place of what it
asked for, <code>unparsed-text()</code> among them,
+ A function that cannot accept an empty document in place of what it
asked for, such as <code>unparsed-text()</code>,
reports an error when the resolver declines rather than returning
empty content;
either way, the resource is not fetched.
</p>
diff --git a/src/site/markdown/threat_model.md
b/src/site/markdown/threat_model.md
index b5cadc4..7ba3e94 100644
--- a/src/site/markdown/threat_model.md
+++ b/src/site/markdown/threat_model.md
@@ -54,7 +54,7 @@ The same holds for parser objects the caller constructs
outside the library and
an `XMLReader` wrapped in a `SAXSource`,
a StAX reader inside a `StAXSource`,
or a document parsed elsewhere and handed over as a `DOMSource`
-are **trusted** configuration, not untrusted input.
+is **trusted** configuration, not untrusted input.
The library secures what it creates;
it does not re-harden what you built,
because your reader's settings are indistinguishable from configuration you
chose deliberately.
@@ -94,7 +94,7 @@ Which securing recipe applies depends on the JAXP
implementation present on the
The guarantees are defined on a single runtime family:
OpenJDK 8 or later (and JDK distributions built from it).
-On these runtimes the recognized parsers apply the processing limits the
guarantees rely on.
+On these runtimes, the recognized parsers apply the processing limits the
guarantees rely on.
Android, on every API level, carries no guarantee:
no version of Android supports `FEATURE_SECURE_PROCESSING`
@@ -107,7 +107,7 @@ but a report demonstrated only on Android is [out of
scope](#What_is_Out_of_Scop
### Honored JAXP contracts
-The in-scope requirement that an implementation respects the contract of the
settings a recipe uses
+The in-scope requirement that an implementation respect the contract of the
settings a recipe uses
(see [What is in scope](#What_is_in_Scope))
extends to the JAXP API contracts themselves.
In particular:
@@ -176,8 +176,8 @@ every one of these defaults bounds the number of expansions,
which is what rejects an exponential payload such as Billion Laughs.
The volume those expansions produce is a separate limit,
and implementations differ on whether they set one by default.
-Sizing it, or provisioning for the load it allows instead,
-is the operator's decision, like the other processing limits above.
+As with the other processing limits above,
+sizing this limit or provisioning for the load it allows is the operator's
decision.
## Reserved Settings
