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-xml.git
commit edaf0281ce26c1f9f6ea07a98d25c4141018c102 Author: Gary Gregory <[email protected]> AuthorDate: Fri Jun 26 17:37:53 2026 +0000 Fix links in site due to missing pages. Use standard Apache Commons component files: - CONTRIBUTING.md - NOTICE.md - README.md - RELEASE-NOTES.txt - src/site files --- CONTRIBUTING.md | 75 +++++++++++ NOTICE.txt | 2 +- README.md | 266 +++++++++++++++------------------------ RELEASE-NOTES.txt | 50 ++++++++ pom.xml | 2 +- src/changes/release-notes.vm | 140 +++++++++++++++++++++ src/site/xdoc/download_xml.xml | 158 +++++++++++++++++++++++ src/site/xdoc/issue-tracking.xml | 104 +++++++++++++++ src/site/xdoc/mail-lists.xml | 215 +++++++++++++++++++++++++++++++ 9 files changed, 844 insertions(+), 168 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5ada0d6..5367393 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,3 +38,78 @@ | | +======================================================================+ ---> +Contributing to Apache Commons XML +====================== + +Have you found a bug or 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. + +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. ++ 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 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 when it is a bug. + + Make sure you fill in the earliest version that you know has the issue. ++ Find the corresponding [repository on GitHub](https://github.com/apache/?query=commons-), +[fork](https://help.github.com/articles/fork-a-repo/) and check out your forked repository. If you don't have a GitHub account, you can still clone the Commons repository. + +Making Changes +-------------- + ++ Create a _topic branch_ for your isolated work. + * Usually you should base your branch from the `master` branch. + * A good topic branch name can be the JIRA bug ID plus a keyword, e.g. `COMMONSXML-123-InputStream`. + * If you have submitted multiple JIRA issues, try to maintain separate branches and pull requests. ++ Make commits of logical units. + * Make sure your commit messages are meaningful and in the proper format. Your commit message should contain the key of the JIRA issue. + * For example, `[COMMONSXML-123] Close input stream sooner` ++ Respect the original code style: + + Only use spaces for indentation; you can check for unnecessary whitespace with `git diff` before committing. + + Create minimal diffs - disable _On Save_ actions like _Reformat Source Code_ or _Organize Imports_. If you feel the source code should be reformatted create a separate PR for this change first. ++ Write unit tests that match behavioral changes, where the tests fail if the changes to the runtime are not applied. This may not always be possible but is a best practice. +Unit tests are typically in the `src/test/java` directory. ++ Run a successful build using the default [Maven](https://maven.apache.org/) goal with `mvn`; that's `mvn` on the command line by itself. ++ Write a pull request description that is detailed enough to understand what the pull request does, how, and why. ++ Each commit in the pull request should have a meaningful subject line and body. Note that commits might be squashed by a maintainer on merge. + + +Making Trivial Changes +---------------------- + +The JIRA tickets are used to generate the changelog for the next release. + +For changes of a trivial nature to comments and documentation, it is not always necessary to create a new ticket in JIRA. +In this case, it is appropriate to start the first line of a commit with '[doc]' or '[javadoc]' instead of a ticket number. + + +Submitting Changes +------------------ + ++ Sign and submit the Apache [Contributor License Agreement][cla] if you haven't already. + * Note that small patches & typical bug fixes do not require a CLA as + clause 5 of the [Apache License](https://www.apache.org/licenses/LICENSE-2.0.html#contributions) + covers them. ++ Push your changes to a topic branch in your fork of the repository. ++ Submit a _Pull Request_ to the corresponding repository in the `apache` organization. + * Verify _Files Changed_ shows only your intended changes and does not + include additional files like `target/*.class` ++ Update your JIRA ticket and include a link to the pull request in the ticket. + +If you prefer to not use GitHub, then you can instead use +`git format-patch` (or `svn diff`) and attach the patch file to the JIRA issue. + + +Additional Resources +-------------------- + ++ [Contributing patches](https://commons.apache.org/patches.html) ++ [Apache Commons XML JIRA project page][jira] ++ [Contributor License Agreement][cla] ++ [General GitHub documentation](https://help.github.com/) ++ [GitHub pull request documentation](https://help.github.com/articles/creating-a-pull-request/) + +[cla]:https://www.apache.org/licenses/#clas +[jira]:https://issues.apache.org/jira/browse/COMMONSXML diff --git a/NOTICE.txt b/NOTICE.txt index 9365449..4d5ac01 100644 --- a/NOTICE.txt +++ b/NOTICE.txt @@ -1,5 +1,5 @@ Apache Commons XML -Copyright 2026 The Apache Software Foundation +Copyright 2026-2026 The Apache Software Foundation This product includes software developed at The Apache Software Foundation (https://www.apache.org/). diff --git a/README.md b/README.md index 40d0807..d32ec7f 100644 --- a/README.md +++ b/README.md @@ -1,187 +1,121 @@ -<!-- -Licensed to the Apache Software Foundation (ASF) under one or more -contributor license agreements. See the NOTICE file distributed with -this work for additional information regarding copyright ownership. -The ASF licenses this file to You under the Apache License, Version 2.0 -(the "License"); you may not use this file except in compliance with -the License. You may obtain a copy of the License at - - https://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -See the License for the specific language governing permissions and -limitations under the License. +<!--- + Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed with + this work for additional information regarding copyright ownership. + The ASF licenses this file to You under the Apache License, Version 2.0 + (the "License"); you may not use this file except in compliance with + the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. --> - -# Apache Commons XML - -> [!WARNING] -> **Sandbox component.** Apache Commons XML is part of the -> [Apache Commons Sandbox](https://commons.apache.org/sandbox/). It is a work in progress, has not been formally -> released, and its API, coordinates, and behaviour may change without notice. Do not rely on it in production. - -Secure-by-default JAXP factory creation for Java. -A single method call returns a hardened JAXP factory that can be used to **safely** parse XML files. - -## Why - -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 -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. - -Defaults are also uneven. The stock JDK SAX and DOM parsers already prevent external entity resolution through -`FEATURE_SECURE_PROCESSING`, and JAXP 1.5 conformant implementations ship reasonable defaults for most attacks. Others, -such as standalone Xerces, Woodstox, or Saxon's TrAX, need further configuration before they reach the same baseline. A -library author has no control over which implementation is on the classpath at runtime, so the effective security -posture of their code depends on a deployment decision made elsewhere. - -This library provides that baseline. Each `XmlFactories` call returns a fresh factory hardened by an -implementation-specific recipe, so the returned object behaves the same way security-wise regardless of which JAXP -implementation resolved. Security becomes a property of the call, not of the classpath, and there is one place to -update when a new hardening setting becomes available or a default changes. - -## Usage - -Add the library to your build: +<!--- + +======================================================================+ + |**** ****| + |**** THIS FILE IS GENERATED BY THE COMMONS BUILD PLUGIN ****| + |**** DO NOT EDIT DIRECTLY ****| + |**** ****| + +======================================================================+ + | TEMPLATE FILE: readme-md-template.md | + | commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates | + +======================================================================+ + | | + | 1) Re-generate using: mvn commons-build:readme-md | + | | + | 2) Set the following properties in the component's pom: | + | - commons.componentid (required, alphabetic, lower case) | + | - commons.release.version (required) | + | | + | 3) Example Properties | + | | + | <properties> | + | <commons.componentid>math</commons.componentid> | + | <commons.release.version>1.2</commons.release.version> | + | </properties> | + | | + +======================================================================+ +---> +Apache Commons XML +=================== + +[](https://github.com/apache/commons-xml/actions/workflows/maven.yml) +[](https://search.maven.org/artifact/org.apache.commons/commons-xml) +[](https://javadoc.io/doc/org.apache.commons/commons-xml/0.1.0) +[](https://github.com/apache/commons-xml/actions/workflows/codeql-analysis.yml) +[](https://api.securityscorecards.dev/projects/github.com/apache/commons-xml) + +Apache Commons XML provides secure-by-default JAXP factory creation, abstracting over + implementation-specific XXE hardening differences between the stock JDK and external JAXP implementations + (Android, Apache Xalan, Apache Xerces, Woodstox, Saxon-HE). + +Documentation +------------- + +More information can be found on the [Apache Commons XML homepage](https://commons.apache.org/proper/commons-xml). +The [Javadoc](https://commons.apache.org/proper/commons-xml/apidocs) can be browsed. +Questions related to the usage of Apache Commons XML should be posted to the [user mailing list](https://commons.apache.org/mail-lists.html). + +Getting the latest release +-------------------------- +You can download source and binaries from our [download page](https://commons.apache.org/proper/commons-xml/download_xml.cgi). + +Alternatively, you can pull it from the central Maven repositories: ```xml <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-xml</artifactId> - <version>0.1.0-SNAPSHOT</version> + <version>0.1.0</version> </dependency> ``` -Every method on `XmlFactories` returns a fresh, hardened factory. Pick the one that matches the API you already use; no -other configuration is required. On hardened factories any attempt to resolve an external resource (DTD, entity, schema, -stylesheet) is blocked, and DOCTYPE input is rejected wherever the underlying implementation allows it. - -Each method is documented in the -[`XmlFactories` Javadoc](https://javadoc.io/doc/org.apache.commons/commons-xml/latest/org/apache/commons/xml/XmlFactories.html), -hosted on javadoc.io. - -### Supported implementations - -The library recognises: - -- the stock JDK JAXP implementations, -- Android, -- Saxon-HE, -- Apache Xalan, -- Apache Xerces, -- Woodstox. - -If a factory resolves to an implementation not covered by any bundled hardening recipe, every `XmlFactories` method throws -`IllegalStateException` with a message naming the unsupported class. Adding support for a new JAXP implementation -requires a code change to this library. - -**DOM parsing** via `DocumentBuilderFactory`: - -```java -import org.w3c.dom.Document; -import org.apache.commons.xml.XmlFactories; - -Document doc = XmlFactories.newDocumentBuilderFactory().newDocumentBuilder().parse(inputStream); -``` - -**SAX parsing** via `SAXParserFactory`: - -```java -import org.apache.commons.xml.XmlFactories; - -XmlFactories.newSAXParserFactory().newSAXParser().parse(inputStream, myDefaultHandler); -``` - -**Streaming (StAX) parsing** via `XMLInputFactory`: - -```java -import javax.xml.stream.XMLStreamReader; -import org.apache.commons.xml.XmlFactories; - -XMLStreamReader reader = XmlFactories.newXMLInputFactory().createXMLStreamReader(inputStream); -``` - -**XSLT transforms** via `TransformerFactory`: +Building +-------- -```java -import javax.xml.transform.stream.StreamSource; -import org.apache.commons.xml.XmlFactories; -XmlFactories.newTransformerFactory() - .newTransformer(new StreamSource(stylesheet)) - .transform(new StreamSource(inputStream), new StreamResult(outputStream)); -``` - -**XPath queries** via `XPathFactory`: - -```java -import javax.xml.xpath.XPathConstants; -import org.w3c.dom.NodeList; -import org.apache.commons.xml.XmlFactories; - -NodeList hits = (NodeList) XmlFactories.newXPathFactory() - .newXPath() - .evaluate("//item", doc, XPathConstants.NODESET); -``` - -**W3C XML Schema validation** via `SchemaFactory`: - -```java -import javax.xml.transform.stream.StreamSource; -import org.apache.commons.xml.XmlFactories; - -XmlFactories.newSchemaFactory() - .newSchema(new StreamSource(xsdStream)) - .newValidator() - .validate(new StreamSource(inputStream)); -``` - -### Stylesheets and schemas - -The hardening applies to documents parsed through the returned factory. Stylesheets given to -`TransformerFactory.newTransformer(Source)` and schemas given to `SchemaFactory.newSchema(Source)` are read by a parser -the implementation picks internally, and that parser may not be hardened (Saxon's TrAX is one such case, see Building -below). Treat stylesheets and schemas as trusted input, or pre-parse them through a hardened `XmlFactories` parser and -pass the result as a `DOMSource` or `SAXSource`. +Building requires a Java JDK and [Apache Maven](https://maven.apache.org/). +The required Java version is found in the `pom.xml` as the `maven.compiler.source` property. -### Android compatibility +From a command shell, run `mvn` without arguments to invoke the default Maven goal to run all tests and checks. -The library is compiled to Java 8 bytecode and runs on any Android version that supports a Java 8 runtime (API 19 and -above). What ships with the platform and what the application has to add varies by JAXP API: +Contributing +------------ -- **DOM** (`DocumentBuilderFactory`) and **SAX** (`SAXParserFactory`) ship in `android.jar` since API 1. DOM is backed by - KXmlParser (a kxml2 pull parser); SAX is a wrapper around the system `libexpat`. The hardened factories returned by - `XmlFactories` route through these built-in implementations. -- **TrAX** (`TransformerFactory`) and **XPath** (`XPathFactory`) ship as Apache Xalan since Android 1.0. The hardened - factories receive the same JDK-style entity-expansion limits and deny-all resolver that the standalone Xalan recipe - applies. -- **W3C XML Schema** (`SchemaFactory`) is **declared** in `android.jar` (the `javax.xml.validation.*` API is present) - but the platform ships **no implementation**. -- **StAX** (`XMLInputFactory`) is **not** part of `android.jar` at any API level. +We accept Pull Requests via GitHub. The [developer mailing list](https://commons.apache.org/mail-lists.html) is the main channel of communication for contributors. +There are some guidelines which will make applying PRs easier for us: ++ No tabs! Please use spaces for indentation. ++ Respect the existing code style for each file. ++ Create minimal diffs - disable on save actions like reformat source code or organize imports. If you feel the source code should be reformatted create a separate PR for this change. ++ Provide JUnit tests for your changes and make sure your changes don't break any existing tests by running `mvn`. ++ Before you push a PR, run `mvn` (without arguments). This runs the default goal which contains all build checks. ++ To see the code coverage report, regardless of coverage failures, run `mvn clean site -Dcommons.jacoco.haltOnFailure=false -Pjacoco` -The SAX path's native billion-laughs amplification protection lives in `libexpat` 2.4 (March 2022), which AOSP first -shipped in **Android 13 (API 33)**. On API 33 and above the platform SAX parser blocks billion-laughs payloads natively; -on older Android releases this specific defence could be unavailable, and a hostile internal-entity payload could -amplify without bound. If your minimum-supported Android level is below 33 and you parse SAX input that you do not -control, sanitise upstream of `XmlFactories`, or pre-parse with Apache Xerces (which carries its own entity-expansion -limit) once you have added it to the classpath for schema support. +If you plan to contribute on a regular basis, please consider filing a [contributor license agreement](https://www.apache.org/licenses/#clas). +You can learn more about contributing via GitHub in our [contribution guidelines](CONTRIBUTING.md). -### Caching and thread-safety +License +------- +This code is licensed under the [Apache License v2](https://www.apache.org/licenses/LICENSE-2.0). -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. +See the `NOTICE.txt` file for required notices and attributions. -## Building +Donating +-------- +You like Apache Commons XML? Then [donate back to the ASF](https://www.apache.org/foundation/contributing.html) to support development. -Building requires a Java JDK and [Apache Maven](https://maven.apache.org/). -The required Java version is found in the `pom.xml` as the `maven.compiler.source` property. +Additional Resources +-------------------- -From a command shell, run `mvn` without arguments to invoke the default Maven goal to run all tests and checks ++ [Apache Commons Homepage](https://commons.apache.org/) ++ [Apache Issue Tracker (JIRA)](https://issues.apache.org/jira/browse/COMMONSXML) ++ [Apache Commons Slack Channel](https://the-asf.slack.com/archives/C60NVB8AD) -## Licensing +Apache Commons Components +------------------------- -Licensed under the Apache License, Version 2.0. See `LICENSE`. ++ [List of Apache Commons components](https://commons.apache.org/components.html): homepages and documentation for all components. ++ [`REPOSITORIES.md`](https://github.com/apache/commons-parent/blob/master/REPOSITORIES.md): overview of the code repositories and their build status. diff --git a/RELEASE-NOTES.txt b/RELEASE-NOTES.txt new file mode 100644 index 0000000..ba4456a --- /dev/null +++ b/RELEASE-NOTES.txt @@ -0,0 +1,50 @@ + +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +Apache Commons XML 0.1.0 Release Notes +-------------------------------------- + +The Apache Commons XML team is pleased to announce the release of Apache Commons XML 0.1.0. + +Apache Commons XML provides secure-by-default JAXP factory creation, abstracting over +implementation-specific XXE hardening differences between the stock JDK and external JAXP implementations +(Android, Apache Xalan, Apache Xerces, Woodstox, Saxon-HE). + +First release. + + +New features +------------ + +* Secure-by-default JAXP factory creation via XmlFactories, with implementation-specific hardening recipes for the + stock JDK, Android, Apache Xalan, Apache Xerces, Woodstox, and Saxon-HE. + + + + +Historical list of changes: https://commons.apache.org/sandbox/commons-xml//changes.html + +For complete information on Apache Commons XML, including instructions on how to submit bug reports, +patches, or suggestions for improvement, see the Apache Commons XML website: + +https://commons.apache.org/sandbox/commons-xml/ + +Download page: https://commons.apache.org/sandbox/commons-xml//download_text.cgi + +Have fun! +-Apache Commons Team + +----------------------------------------------------------------------------- diff --git a/pom.xml b/pom.xml index f9aa583..727c315 100644 --- a/pom.xml +++ b/pom.xml @@ -64,7 +64,7 @@ limitations under the License. <properties> <!-- Release-related properties --> - <commons.release.version>0.1.1</commons.release.version> + <commons.release.version>0.1.0</commons.release.version> <commons.release.desc>(Java 8+)</commons.release.desc> <commons.rc.version>RC1</commons.rc.version> <!-- japicmp baseline: disable for first release diff --git a/src/changes/release-notes.vm b/src/changes/release-notes.vm new file mode 100644 index 0000000..b50d932 --- /dev/null +++ b/src/changes/release-notes.vm @@ -0,0 +1,140 @@ +## Licensed to the Apache Software Foundation (ASF) under one +## or more contributor license agreements. See the NOTICE file +## distributed with this work for additional information +## regarding copyright ownership. The ASF licenses this file +## to you under the Apache License, Version 2.0 (the +## "License"); you may not use this file except in compliance +## with the License. You may obtain a copy of the License at +## +## https://www.apache.org/licenses/LICENSE-2.0 +## +## Unless required by applicable law or agreed to in writing, +## software distributed under the License is distributed on an +## "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +## KIND, either express or implied. See the License for the +## specific language governing permissions and limitations +## under the License. +## + +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. + +${project.name} ${version} Release Notes +-------------------------------------- + +The ${developmentTeam} is pleased to announce the release of ${project.name} ${version}. + +$introduction.replaceAll("(?<!\015)\012", " +").replaceAll("(?m)^ +","") + +## The available variables are described here: +## http://maven.apache.org/plugins/maven-changes-plugin/examples/using-a-custom-announcement-template.html +## +## Hack to improve layout: replace all pairs of spaces with a single new-line +$release.description.replaceAll(" ", " +") + +## set up indent sizes. Only change indent1 +#set($props=${project.properties}) +#set($jiralen=$props.get("commons.jira.id").length()) +## indent1 = POOL-nnnn: +#set($blanklen=$jiralen+6)## +6 for "-nnnn:" +## must be at least as long as the longest JIRA id +#set($blanks=" ") +#set($indent1=$blanks.substring(0,$blanklen)) +## indent2 allows for issue wrapper +#set($indent2="$indent1 ") +## +#macro ( processaction ) +## Use replaceAll to fix up LF-only line ends on Windows. +#set($action=$actionItem.getAction().replaceAll("\n"," +")) +## Fix up indentation for multi-line action descriptions +#set($action=$action.replaceAll("(?m)^ +",$indent2)) +#if ($actionItem.getIssue()) +#set($issue="$actionItem.getIssue():") +## Pad shorter issue numbers +#if ($issue.length() < $indent1.length())#set ($issue="$issue ")#end +#if ($issue.length() < $indent1.length())#set ($issue="$issue ")#end +#if ($issue.length() < $indent1.length())#set ($issue="$issue ")#end +#else +#set($issue=$indent1) +#end +#if ($actionItem.getDueTo()) +#set($dueto=" Thanks to $actionItem.getDueTo().") +#else +#set($dueto="") +#end +* $issue ${action}$dueto +#set($action="") +#set($issue="") +#set($dueto="") +#end +## +#if ($release.getActions().size() == 0) +No changes defined in this version. +#else + +#if ($release.getActions('add').size() !=0) +New features +------------ + +#foreach($actionItem in $release.getActions('add')) +#processaction() +#end +#end + +#if ($release.getActions('fix').size() !=0) +Fixed Bugs +---------- + +#foreach($actionItem in $release.getActions('fix')) +#processaction() +#end +#end + +#if ($release.getActions('update').size() !=0) +Changes +------- + +#foreach($actionItem in $release.getActions('update')) +#processaction() +#end +#end + +#if ($release.getActions('remove').size() !=0) +Removed +------- + +#foreach($actionItem in $release.getActions('remove')) +#processaction() +#end +#end +## End of main loop +#end + +Historical list of changes: ${project.url}/changes.html + +For complete information on ${project.name}, including instructions on how to submit bug reports, +patches, or suggestions for improvement, see the ${project.name} website: + +${project.url} + +Download page: ${project.url}/download_text.cgi + +Have fun! +-Apache Commons Team + +----------------------------------------------------------------------------- diff --git a/src/site/xdoc/download_xml.xml b/src/site/xdoc/download_xml.xml new file mode 100644 index 0000000..d666604 --- /dev/null +++ b/src/site/xdoc/download_xml.xml @@ -0,0 +1,158 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +<!-- + +======================================================================+ + |**** ****| + |**** THIS FILE IS GENERATED BY THE COMMONS BUILD PLUGIN ****| + |**** DO NOT EDIT DIRECTLY ****| + |**** ****| + +======================================================================+ + | TEMPLATE FILE: download-page-template.xml | + | commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates | + +======================================================================+ + | | + | 1) Re-generate using: mvn commons-build:download-page | + | | + | 2) Set the following properties in the component's pom: | + | - commons.componentid (required, alphabetic, lower case) | + | - commons.release.version (required) | + | - commons.release.name (required) | + | - commons.binary.suffix (optional) | + | (defaults to "-bin", set to "" for pre-maven2 releases) | + | - commons.release.desc (optional) | + | - commons.release.subdir (optional) | + | - commons.release.hash (optional, lowercase, default sha512) | + | | + | - commons.release.[234].version (conditional) | + | - commons.release.[234].name (conditional) | + | - commons.release.[234].binary.suffix (optional) | + | - commons.release.[234].desc (optional) | + | - commons.release.[234].subdir (optional) | + | - commons.release.[234].hash (optional, lowercase, [sha512])| + | | + | 3) Example Properties | + | (commons.release.name inherited by parent: | + | ${project.artifactId}-${commons.release.version} | + | | + | <properties> | + | <commons.componentid>math</commons.componentid> | + | <commons.release.version>1.2</commons.release.version> | + | </properties> | + | | + +======================================================================+ +--> +<document xmlns="http://maven.apache.org/XDOC/2.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 https://maven.apache.org/xsd/xdoc-2.0.xsd";> + <properties> + <title>Download Apache Commons XML</title> + <author email="[email protected]">Apache Commons Team</author> + </properties> + <body> + <section name="Download Apache Commons XML"> + <subsection name="Using a Mirror"> + <p> + We recommend you use a mirror to download our release + builds, but you <strong>must</strong> <a href="https://www.apache.org/info/verification.html";>verify the integrity</a> of + the downloaded files using signatures downloaded from our main + distribution directories. Recent releases (48 hours) may not yet + be available from all the mirrors. + </p> + + <p> + You are currently using <b>[preferred]</b>. If you + encounter a problem with this mirror, please select another + mirror. If all mirrors are failing, there are <i>backup</i> + mirrors (at the end of the mirrors list) that should be + available. + <br></br> + [if-any logo]<a href="[link]"><img align="right" src="[logo]" border="0" alt="Logo"></img></a>[end] + </p> + + <form action="[location]" method="get" id="SelectMirror"> + <p> + Other mirrors: + <select name="Preferred"> + [if-any http] + [for http]<option value="[http]">[http]</option>[end] + [end] + [if-any ftp] + [for ftp]<option value="[ftp]">[ftp]</option>[end] + [end] + [if-any backup] + [for backup]<option value="[backup]">[backup] (backup)</option>[end] + [end] + </select> + <input type="submit" value="Change"></input> + </p> + </form> + + <p> + It is essential that you + <a href="https://www.apache.org/info/verification.html";>verify the integrity</a> + of downloaded files, preferably using the <code>PGP</code> signature (<code>*.asc</code> files); + failing that using the <code>SHA512</code> hash (<code>*.sha512</code> checksum files). + </p> + <p> + The <a href="https://downloads.apache.org/commons/KEYS";>KEYS</a> + file contains the public PGP keys used by Apache Commons developers + to sign releases. + </p> + </subsection> + </section> + <section name="Apache Commons XML 0.1.0 (Java 8+)"> + <subsection name="Binaries"> + <table> + <tr> + <td><a href="[preferred]/commons/xml/binaries/commons-xml-0.1.0-bin.tar.gz">commons-xml-0.1.0-bin.tar.gz</a></td> + <td><a href="https://downloads.apache.org/commons/xml/binaries/commons-xml-0.1.0-bin.tar.gz.sha512";>sha512</a></td> + <td><a href="https://downloads.apache.org/commons/xml/binaries/commons-xml-0.1.0-bin.tar.gz.asc";>pgp</a></td> + </tr> + <tr> + <td><a href="[preferred]/commons/xml/binaries/commons-xml-0.1.0-bin.zip">commons-xml-0.1.0-bin.zip</a></td> + <td><a href="https://downloads.apache.org/commons/xml/binaries/commons-xml-0.1.0-bin.zip.sha512";>sha512</a></td> + <td><a href="https://downloads.apache.org/commons/xml/binaries/commons-xml-0.1.0-bin.zip.asc";>pgp</a></td> + </tr> + </table> + </subsection> + <subsection name="Source"> + <table> + <tr> + <td><a href="[preferred]/commons/xml/source/commons-xml-0.1.0-src.tar.gz">commons-xml-0.1.0-src.tar.gz</a></td> + <td><a href="https://downloads.apache.org/commons/xml/source/commons-xml-0.1.0-src.tar.gz.sha512";>sha512</a></td> + <td><a href="https://downloads.apache.org/commons/xml/source/commons-xml-0.1.0-src.tar.gz.asc";>pgp</a></td> + </tr> + <tr> + <td><a href="[preferred]/commons/xml/source/commons-xml-0.1.0-src.zip">commons-xml-0.1.0-src.zip</a></td> + <td><a href="https://downloads.apache.org/commons/xml/source/commons-xml-0.1.0-src.zip.sha512";>sha512</a></td> + <td><a href="https://downloads.apache.org/commons/xml/source/commons-xml-0.1.0-src.zip.asc";>pgp</a></td> + </tr> + </table> + </subsection> + </section> + <section name="Archives"> + <p> + Older releases can be obtained from the archives. + </p> + <ul> + <li class="download"><a href="[preferred]/commons/xml/">browse download area</a></li> + <li><a href="https://archive.apache.org/dist/commons/xml/";>archives...</a></li> + </ul> + </section> + </body> +</document> diff --git a/src/site/xdoc/issue-tracking.xml b/src/site/xdoc/issue-tracking.xml new file mode 100644 index 0000000..d081a0d --- /dev/null +++ b/src/site/xdoc/issue-tracking.xml @@ -0,0 +1,104 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +<!-- + +======================================================================+ + |**** ****| + |**** THIS FILE IS GENERATED BY THE COMMONS BUILD PLUGIN ****| + |**** DO NOT EDIT DIRECTLY ****| + |**** ****| + +======================================================================+ + | TEMPLATE FILE: issue-tracking-template.xml | + | commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates | + +======================================================================+ + | | + | 1) Re-generate using: mvn commons-build:jira-page | + | | + | 2) Set the following properties in the component's pom: | + | - commons.jira.id (required, alphabetic, upper case) | + | - commons.jira.pid (required, numeric) | + | | + | 3) Example Properties | + | | + | <properties> | + | <commons.jira.id>MATH</commons.jira.id> | + | <commons.jira.pid>12310485</commons.jira.pid> | + | </properties> | + | | + +======================================================================+ +--> +<document xmlns="http://maven.apache.org/XDOC/2.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 https://maven.apache.org/xsd/xdoc-2.0.xsd";> + <properties> + <title>Apache Commons XML Issue tracking</title> + <author email="[email protected]">Apache Commons Team</author> + </properties> + <body> + + <section name="Apache Commons XML Issue tracking"> + <p> + Apache Commons XML uses <a href="https://issues.apache.org/jira/";>ASF JIRA</a> for tracking issues. + See the <a href="https://issues.apache.org/jira/browse/COMMONSXML";>Apache Commons XML JIRA project page</a>. + </p> + + <p> + To use JIRA you may need to <a href="https://issues.apache.org/jira/secure/Signup!default.jspa";>create an account</a> + (if you have previously created/updated Commons issues using Bugzilla an account will have been automatically + created and you can use the <a href="https://issues.apache.org/jira/secure/ForgotPassword!default.jspa";>Forgot Password</a> + page to get a new password). + </p> + + <p> + If you would like to report a bug, or raise an enhancement request with + Apache Commons XML please do the following: + </p> + <ol> + <li><a href="https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&pid=${commons.jira.pid}&sorter/field=issuekey&sorter/order=DESC&status=1&status=3&status=4";>Search existing open bugs</a>. + If you find your issue listed then please add a comment with your details.</li> + <li><a href="mail-lists.html">Search the mailing list archive(s)</a>. + You may find your issue or idea has already been discussed.</li> + <li>Decide if your issue is a bug or an enhancement.</li> + <li>Submit either a <a href="https://issues.apache.org/jira/secure/CreateIssueDetails!init.jspa?pid=${commons.jira.pid}&issuetype=1&priority=4&assignee=-1";>bug report</a> + or <a href="https://issues.apache.org/jira/secure/CreateIssueDetails!init.jspa?pid=${commons.jira.pid}&issuetype=4&priority=4&assignee=-1";>enhancement request</a>.</li> + </ol> + + <p> + Please also remember these points: + </p> + <ul> + <li>the more information you provide, the better we can help you</li> + <li>test cases are vital, particularly for any proposed enhancements</li> + <li>the developers of Apache Commons XML are all unpaid volunteers</li> + </ul> + + <p> + For more information on creating patches see the + <a href="https://www.apache.org/dev/contributors.html";>Apache Contributors Guide</a>. + </p> + + <p> + You may also find these links useful: + </p> + <ul> + <li><a href="https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&pid=${commons.jira.pid}&sorter/field=issuekey&sorter/order=DESC&status=1&status=3&status=4";>All Open Apache Commons XML bugs</a></li> + <li><a href="https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&pid=${commons.jira.pid}&sorter/field=issuekey&sorter/order=DESC&status=5&status=6";>All Resolved Apache Commons XML bugs</a></li> + <li><a href="https://issues.apache.org/jira/secure/IssueNavigator.jspa?reset=true&pid=${commons.jira.pid}&sorter/field=issuekey&sorter/order=DESC";>All Apache Commons XML bugs</a></li> + </ul> + </section> + </body> +</document> diff --git a/src/site/xdoc/mail-lists.xml b/src/site/xdoc/mail-lists.xml new file mode 100644 index 0000000..0beecdc --- /dev/null +++ b/src/site/xdoc/mail-lists.xml @@ -0,0 +1,215 @@ +<?xml version="1.0"?> +<!-- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + + https://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +<!-- + +======================================================================+ + |**** ****| + |**** THIS FILE IS GENERATED BY THE COMMONS BUILD PLUGIN ****| + |**** DO NOT EDIT DIRECTLY ****| + |**** ****| + +======================================================================+ + | TEMPLATE FILE: mail-lists-template.xml | + | commons-build-plugin/trunk/src/main/resources/commons-xdoc-templates | + +======================================================================+ + | | + | 1) Re-generate using: mvn commons-build:mail-page | + | | + | 2) Set the following properties in the component's pom: | + | - commons.componentid (required, alphabetic, lower case) | + | | + | 3) Example Properties | + | | + | <properties> | + | <commons.componentid>math</commons.componentid> | + | </properties> | + | | + +======================================================================+ +--> +<document xmlns="http://maven.apache.org/XDOC/2.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 https://maven.apache.org/xsd/xdoc-2.0.xsd";> + <properties> + <title>Apache Commons XML Mailing Lists</title> + <author email="[email protected]">Apache Commons Team</author> + </properties> + <body> + + <section name="Overview"> + <p> + <a href="index.html">Apache Commons XML</a> shares mailing lists with all the other + <a href="https://commons.apache.org/components.html";>Commons Components</a>. + To make it easier for people to only read messages related to components they are interested in, + the convention in Commons is to prefix the subject line of messages with the component's name, + for example: + </p> + <ul> + <li>[xml] Problem with the ...</li> + </ul> + <p> + Questions related to the usage of Apache Commons XML should be posted to the + <a href="https://lists.apache.org/[email protected]";>User List</a>. + <br /> + The <a href="https://lists.apache.org/[email protected]";>Developer List</a> + is for questions and discussion related to the development of Apache Commons XML. + <br /> + Please do not cross-post; developers are also subscribed to the user list. + <br /> + You must be subscribed to post to the mailing lists. Follow the Subscribe links below + to subscribe. + </p> + <p> + <strong>Note:</strong> please don't send patches or attachments to any of the mailing lists; + most of the lists are set up to drop attachments. + Patches are best handled via the <a href="issue-tracking.html">Issue Tracking</a> system. + If you have a GitHub account, most components also accept PRs (pull requests). + Otherwise, please upload the file to a public server and include the URL in the mail. + </p> + </section> + + <section name="Apache Commons XML Mailing Lists"> + <p> + <strong>Please prefix the subject line of any messages for <a href="index.html">Apache Commons XML</a> + with <i>[xml]</i></strong> - <i>thanks!</i> + <br /> + <br /> + </p> + + <table> + <tr> + <th>Name</th> + <th>Subscribe</th> + <th>Unsubscribe</th> + <th>Post</th> + <th>Archive</th> + <th>Other Archives</th> + </tr> + + + <tr> + <td> + <strong>Commons User List</strong> + <br /><br /> + Questions on using Apache Commons XML. + <br /><br /> + </td> + <td><a href="mailto:[email protected]";>Subscribe</a></td> + <td><a href="mailto:[email protected]";>Unsubscribe</a></td> + <td><a href="mailto:[email protected]?subject=[xml]";>Post</a></td> + <td> + <a href="https://lists.apache.org/[email protected]";>lists.apache.org</a> + </td> + <td> + <a href="https://www.mail-archive.com/[email protected]/";>www.mail-archive.com</a> + </td> + </tr> + + + <tr> + <td> + <strong>Commons Developer List</strong> + <br /><br /> + Discussion of development of Apache Commons XML. + <br /><br /> + </td> + <td><a href="mailto:[email protected]";>Subscribe</a></td> + <td><a href="mailto:[email protected]";>Unsubscribe</a></td> + <td><a href="mailto:[email protected]?subject=[xml]";>Post</a></td> + <td> + <a href="https://lists.apache.org/[email protected]";>lists.apache.org</a> + </td> + <td> + <a href="https://www.mail-archive.com/[email protected]/";>www.mail-archive.com</a> + </td> + </tr> + + + <tr> + <td> + <strong>Commons Issues List</strong> + <br /><br /> + Only for e-mails automatically generated by the <a href="issue-tracking.html">issue tracking</a> system. + <br /><br /> + </td> + <td><a href="mailto:[email protected]";>Subscribe</a></td> + <td><a href="mailto:[email protected]";>Unsubscribe</a></td> + <td><i>read only</i></td> + <td> + <a href="https://lists.apache.org/[email protected]";>lists.apache.org</a> + </td> + <td> + <a href="https://www.mail-archive.com/[email protected]/";>www.mail-archive.com</a> + </td> + </tr> + + + <tr> + <td> + <strong>Commons Commits List</strong> + <br /><br /> + Only for e-mails automatically generated by the <a href="scm.html">source control</a> system. + <br /><br /> + </td> + <td><a href="mailto:[email protected]";>Subscribe</a></td> + <td><a href="mailto:[email protected]";>Unsubscribe</a></td> + <td><i>read only</i></td> + <td> + <a href="https://lists.apache.org/[email protected]";>lists.apache.org</a> + </td> + <td> + <a href="https://www.mail-archive.com/[email protected]/";>www.mail-archive.com</a> + </td> + </tr> + + </table> + + </section> + <section name="Apache Mailing Lists"> + <p> + Other mailing lists which you may find useful include: + </p> + + <table> + <tr> + <th>Name</th> + <th>Subscribe</th> + <th>Unsubscribe</th> + <th>Post</th> + <th>Archive</th> + <th>Other Archives</th> + </tr> + <tr> + <td> + <strong>Apache Announce List</strong> + <br /><br /> + General announcements of Apache project releases. + <br /><br /> + </td> + <td><a class="externalLink" href="mailto:[email protected]";>Subscribe</a></td> + <td><a class="externalLink" href="mailto:[email protected]";>Unsubscribe</a></td> + <td><i>read only</i></td> + <td> + <a class="externalLink" href="https://lists.apache.org/[email protected]";>lists.apache.org</a> + </td> + <td> + <a class="externalLink" href="https://www.mail-archive.com/[email protected]/";>www.mail-archive.com</a> + </td> + </tr> + </table> + + </section> + </body> +</document>
