diff --git a/.github/workflows/codecov.yml b/.github/workflows/codecov.yml new file mode 100644 index 0000000..5b388a8 --- /dev/null +++ b/.github/workflows/codecov.yml @@ -0,0 +1,28 @@ +# This is a basic workflow to help you get started with Actions + +name: Codecov + +# Controls when the action will run. Triggers the workflow on push or pull request +# events but only for the master branch +on: + push: + pull_request: + + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + build: + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - uses: actions/checkout@v2 + + - name: Run cobertura + run: mvn cobertura:cobertura + + - name: Upload report + run: bash <(curl -s https://codecov.io/bash) diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml new file mode 100644 index 0000000..87ce66d --- /dev/null +++ b/.github/workflows/maven.yml @@ -0,0 +1,31 @@ +# This workflow will build a Java project with Maven +# For more information see: https://help.github.com/actions/language-and-framework-guides/building-and-testing-java-with-maven + +name: Build + +on: + push: + pull_request: + +jobs: + build: + + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + java: [7, 8, 9.0.x, 10, 11, 12, 13] + + steps: + - uses: actions/checkout@v2 + + - name: Set up JDK + uses: actions/setup-java@v1 + with: + java-version: ${{ matrix.java }} + + - name: Clean Build + run: mvn clean + + - name: Build with Maven + run: mvn -B package --file pom.xml \ No newline at end of file diff --git a/.gitignore b/.gitignore index 762f6e9..84a1064 100644 --- a/.gitignore +++ b/.gitignore @@ -2,8 +2,8 @@ /.classpath /.project /.settings +/.envrc /mvn -/HOWTO_RELEASE.txt /bin /target /java-xmlbuilder diff --git a/CHANGES.md b/CHANGES.md index 53f8b53..4b2435f 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,6 +1,18 @@ Release Notes for java-xmlbuilder ================================= +Version 1.3 - 8 July 2020 +------------------------- + +Fixes: + +* Update source version from 1.5 to 1.7 to work with Java versions 11+ which no + longer supports `javax.annotation` and because 6 no longer builds with Maven. + +* Tweaks to pom.xml to get Maven builds to work with Java 12. + +* Replace references to my defunct website with working alternatives. + Version 1.2 - 1 September 2017 ------------------------------ @@ -9,16 +21,16 @@ Fixes: * Prevent XML External Entity (XXE) injection attacks by disabling parsing of general and parameter external entities by default (#6). External entities are now only parsed if this feature is explicitly enabled by passing a boolean - flag value to the #create and #parse methods. + flag value to the #create and #parse methods. WARNING: This will break code that expects external entities to be parsed. - + Enhancements: * Permit users to disable namespace-awareness in the underlying DocumentBuilderFactory when constructing the builder with extended `create()` and `parse()` methods. Namespace awareness is enabled by default unless you use the more explicit versions of these methods that take additional - `enableExternalEntities` and `isNamespaceAware` parameters. + `enableExternalEntities` and `isNamespaceAware` parameters. Version 1.1 - 22 July 2014 -------------------------- @@ -27,12 +39,12 @@ Added a new `XMLBuilder2` implementation that avoids checked exceptions in the API and throws runtime exceptions instead. This should make the library much more pleasant to use, and your code much cleaner, in situations where low-level exceptions are unlikely -- which is probably most situations where you would -use this library. +use this library. For example when creating a new document with the `#create` method, instead of needing to explicitly catch the unlikely `ParserConfigurationException`, if you use `XMLBuilder2` this exception automatically gets wrapped in the new -`XMLBuilderRuntimeException` class and can be left to propagate out. +`XMLBuilderRuntimeException` class and can be left to propagate out. Aside from the removal of checked exceptions, `XMLBuilder2` has the same API as the original `XMLBuilder` and should therefore be a drop-in replacement in @@ -45,9 +57,9 @@ Version 1.0 - 6 March 2014 -------------------------- Jumped version number from 0.7 to 1.0 to better reflect this project's age -and stability, as well as to celebrate the move to GitHub. +and stability, as well as to celebrate the move to GitHub. -* Migrated project from +* Migrated project from [Google Code](https://code.google.com/p/java-xmlbuilder/) to [GitHub](https://github.com/jmurty/java-xmlbuilder). Whew, that's better! * Test cases for edge-case issues and questions reported by users. @@ -91,7 +103,7 @@ Version 0.3 - 2 July 2010 * First release to Maven repository. * Parse existing XML documents with `parse` method. -* Find specific nodes in document with an XPath with `xpathFind`. +* Find specific nodes in document with an XPath with `xpathFind`. * Added JUnit tests Version 0.2 - 6 January 2009 diff --git a/README.md b/README.md index 9181ecb..51bda75 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,12 @@ java-xmlbuilder =============== +[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.jamesmurty.utils/java-xmlbuilder/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.jamesmurty.utils/java-xmlbuilder) + +![Build](https://github.com/jmurty/java-xmlbuilder/workflows/Build/badge.svg) ![Codecov](https://github.com/jmurty/java-xmlbuilder/workflows/Codecov/badge.svg) + +[![codecov](https://codecov.io/gh/jmurty/java-xmlbuilder/branch/master/graph/badge.svg)](https://codecov.io/gh/jmurty/java-xmlbuilder) + XML Builder is a utility that allows simple XML documents to be constructed using relatively sparse Java code. @@ -24,14 +30,14 @@ Since version 1.1 this library provides two builder implementations and APIs: * `XMLBuilder` – the original API – follows standard Java practice of re-throwing lower level checked exceptions when you do things like create a - new document. + new document. You must explicitly `catch` these checked exceptions in your codebase, even - though they are unlikely to occur in tested code. + though they are unlikely to occur in tested code. * `XMLBuilder2` is a newer API that removes checked exceptions altogether, and will instead wrap and propagate lower level exceptions in an unchecked - `XMLBuilderRuntimeException`. + `XMLBuilderRuntimeException`. Use this class if you don't like the code mess or overhead of try/catching - many low-level exceptions that are unlikely to occur in practice. + many low-level exceptions that are unlikely to occur in practice. Both these versions work identically apart from the handling of errors, so you can use whichever version you prefer or "upgrade" from one to the other in @@ -73,11 +79,11 @@ Produces this XML document: Getting Started --------------- -See further example usage below and in the -[JavaDoc documentation](http://s3.jamesmurty.com/java-xmlbuilder/index.html). +See further example usage below and in the +[JavaDoc documentation](http://s3.james.murty.co/java-xmlbuilder/index.html). Download a Jar file containing the latest version -[java-xmlbuilder-1.2.jar](http://s3.jamesmurty.com/java-xmlbuilder/java-xmlbuilder-1.2.jar). +[java-xmlbuilder-1.3.jar](http://s3.james.murty.co/java-xmlbuilder/java-xmlbuilder-1.3.jar). Maven users can add this project as a dependency with the following additions to a POM.xml file: @@ -88,7 +94,7 @@ to a POM.xml file: com.jamesmurty.utils java-xmlbuilder - 1.2 + 1.3 . . . @@ -193,7 +199,7 @@ methods. XMLBuilder builder = XMLBuilder.create("Projects") .e("java-xmlbuilder") .a("language", "Java") - .a("scm","SVN") + .a("scm","SVN") .e("Location") .a("type", "URL") .t("http://code.google.com/p/java-xmlbuilder/") @@ -221,7 +227,7 @@ The following methods are available for adding items to the XML document: ### Output -XMLBuilder includes two convenient methods for outputting a document. +XMLBuilder includes two convenient methods for outputting a document. You can use the `toWriter` method to print the document to an output stream or file: @@ -238,7 +244,7 @@ builder.asString(outputProperties); Both of these output methods take an `outputProperties` parameter that you can use to control how the output is generated. Any output properties you provide are forwarded to the underlying Transformer object that is used to serialize -the XML document. +the XML document. You might specify any non-standard properties like so: @@ -284,7 +290,7 @@ represents the document's root element, no matter deep an element hierarchy your code has built: ```java -org.w3c.dom.Element rootElement = +org.w3c.dom.Element rootElement = XMLBuilder.create("This") .e("Element") .e("Hierarchy") @@ -359,13 +365,13 @@ constructors. You can: -* use the `enableExternalEntities` flag to enable or disable external entities. +* use the `enableExternalEntities` flag to enable or disable external entities. NOTE: you should leave these disabled, as they are by default, unless you really need them because they open you to XML External Entity (XXE) injection attacks. * use the `isNamespaceAware` flag to enable or disable namespace awareness in the underlying `DocumentBuilderFactory`. - + Release History --------------- diff --git a/pom.xml b/pom.xml index 88d5285..cecbdb2 100644 --- a/pom.xml +++ b/pom.xml @@ -4,10 +4,15 @@ java-xmlbuilder jar - 1.3-SNAPSHOT + 1.4-SNAPSHOT java-xmlbuilder XML Builder is a utility that creates simple XML documents using relatively sparse Java code https://github.com/jmurty/java-xmlbuilder + + + 1.7 + 1.7 + @@ -28,7 +33,7 @@ jmurty James Murty - http://jamesmurty.com + https://github.com/jmurty developer @@ -46,7 +51,7 @@ junit junit - 4.11 + 4.13.1 test @@ -89,6 +94,9 @@ org.apache.maven.plugins maven-javadoc-plugin 2.9 + + 7 + attach-javadocs @@ -98,7 +106,19 @@ - + + + org.codehaus.mojo + cobertura-maven-plugin + 2.7 + + + html + xml + + + + diff --git a/src/main/java/com/jamesmurty/utils/BaseXMLBuilder.java b/src/main/java/com/jamesmurty/utils/BaseXMLBuilder.java index c9466f7..3122a30 100644 --- a/src/main/java/com/jamesmurty/utils/BaseXMLBuilder.java +++ b/src/main/java/com/jamesmurty/utils/BaseXMLBuilder.java @@ -1,5 +1,5 @@ /* - * Copyright 2008-2017 James Murty (www.jamesmurty.com) + * Copyright 2008-2020 James Murty (github.com/jmurty) * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -205,8 +205,8 @@ protected static void enableOrDisableExternalEntityParsing( * @return * an XML Document. * - * @throws FactoryConfigurationError - * @throws ParserConfigurationException + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz */ protected static Document createDocumentImpl( String name, String namespaceURI, boolean enableExternalEntities, @@ -240,12 +240,12 @@ protected static Document createDocumentImpl( * {@link DocumentBuilderFactory} * @return * a builder node that can be used to add more nodes to the XML document. - * @throws ParserConfigurationException * - * @throws FactoryConfigurationError - * @throws ParserConfigurationException - * @throws IOException - * @throws SAXException + * @throws ParserConfigurationException xyz + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz + * @throws IOException xyz + * @throws SAXException xyz */ protected static Document parseDocumentImpl( InputSource inputSource, boolean enableExternalEntities, @@ -268,7 +268,7 @@ protected static Document parseDocumentImpl( * Uses approach I documented on StackOverflow: * http://stackoverflow.com/a/979606/4970 * - * @throws XPathExpressionException + * @throws XPathExpressionException xyz */ protected void stripWhitespaceOnlyTextNodesImpl() throws XPathExpressionException @@ -297,7 +297,7 @@ protected void stripWhitespaceOnlyTextNodesImpl() * * @return * a builder node at the same location as before the operation. - * @throws XPathExpressionException + * @throws XPathExpressionException xyz */ public abstract BaseXMLBuilder stripWhitespaceOnlyTextNodes() throws XPathExpressionException; @@ -533,7 +533,7 @@ protected String lookupNamespaceURIImpl(String name) { * the name of the XML element. * @param namespaceURI * a namespace URI - * @return + * @return xyz * * @throws IllegalStateException * if you attempt to add a child element to an XML node that already @@ -757,6 +757,7 @@ protected Element elementImpl(String name, String namespaceURI) { * * @param name * the name of the XML element. + * @return xyz * * @throws IllegalStateException * if you attempt to add a sibling element to a node where there are already @@ -776,6 +777,7 @@ protected Element elementBeforeImpl(String name) { * the name of the XML element. * @param namespaceURI * a namespace URI + * @return xyz * * @throws IllegalStateException * if you attempt to add a sibling element to a node where there are already @@ -1253,6 +1255,8 @@ protected Node upImpl(int steps) { } /** + * @param anXmlElement xyz + * * @throws IllegalStateException * if the current element contains any child text nodes that aren't pure whitespace. * We allow whitespace so parsed XML documents containing indenting or pretty-printing @@ -1298,7 +1302,7 @@ protected void assertElementContainsNoOrWhitespaceOnlyTextNodes(Node anXmlElemen * null or an empty Properties object, in which case the default output * properties will be applied. * - * @throws TransformerException + * @throws TransformerException xyz */ public void toWriter(boolean wholeDocument, Writer writer, Properties outputProperties) throws TransformerException { @@ -1337,7 +1341,7 @@ public void toWriter(boolean wholeDocument, Writer writer, Properties outputProp * null or an empty Properties object, in which case the default output * properties will be applied. * - * @throws TransformerException + * @throws TransformerException xyz */ public void toWriter(Writer writer, Properties outputProperties) throws TransformerException { @@ -1358,7 +1362,7 @@ public void toWriter(Writer writer, Properties outputProperties) * @return * the XML document as a string * - * @throws TransformerException + * @throws TransformerException xyz */ public String asString(Properties outputProperties) throws TransformerException { StringWriter writer = new StringWriter(); @@ -1380,7 +1384,7 @@ public String asString(Properties outputProperties) throws TransformerException * @return * the XML document as a string * - * @throws TransformerException + * @throws TransformerException xyz */ public String elementAsString(Properties outputProperties) throws TransformerException { StringWriter writer = new StringWriter(); @@ -1395,7 +1399,7 @@ public String elementAsString(Properties outputProperties) throws TransformerExc * the XML document as a string without the XML declaration at the * beginning of the output. * - * @throws TransformerException + * @throws TransformerException xyz */ public String asString() throws TransformerException { Properties outputProperties = new Properties(); @@ -1411,7 +1415,7 @@ public String asString() throws TransformerException { * the XML document as a string without the XML declaration at the * beginning of the output. * - * @throws TransformerException + * @throws TransformerException xyz */ public String elementAsString() throws TransformerException { Properties outputProperties = new Properties(); @@ -1438,4 +1442,4 @@ protected String getPrefixFromQualifiedName(String qualifiedName) { } } -} \ No newline at end of file +} diff --git a/src/main/java/com/jamesmurty/utils/XMLBuilder.java b/src/main/java/com/jamesmurty/utils/XMLBuilder.java index 77c50b0..144293f 100644 --- a/src/main/java/com/jamesmurty/utils/XMLBuilder.java +++ b/src/main/java/com/jamesmurty/utils/XMLBuilder.java @@ -1,5 +1,5 @@ /* - * Copyright 2008-2017 James Murty (www.jamesmurty.com) + * Copyright 2008-2020 James Murty (github.com/jmurty) * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -107,8 +107,8 @@ protected XMLBuilder(Node myNode, Node parentNode) { * @return * a builder node that can be used to add more nodes to the XML document. * - * @throws FactoryConfigurationError - * @throws ParserConfigurationException + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz */ public static XMLBuilder create(String name, String namespaceURI, boolean enableExternalEntities, boolean isNamespaceAware) @@ -134,8 +134,8 @@ public static XMLBuilder create(String name, String namespaceURI, * @return * a builder node that can be used to add more nodes to the XML document. * - * @throws FactoryConfigurationError - * @throws ParserConfigurationException + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz */ public static XMLBuilder create(String name, boolean enableExternalEntities, boolean isNamespaceAware) @@ -158,8 +158,8 @@ public static XMLBuilder create(String name, boolean enableExternalEntities, * @return * a builder node that can be used to add more nodes to the XML document. * - * @throws FactoryConfigurationError - * @throws ParserConfigurationException + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz */ public static XMLBuilder create(String name, String namespaceURI) throws ParserConfigurationException, FactoryConfigurationError @@ -177,8 +177,8 @@ public static XMLBuilder create(String name, String namespaceURI) * @return * a builder node that can be used to add more nodes to the XML document. * - * @throws FactoryConfigurationError - * @throws ParserConfigurationException + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz */ public static XMLBuilder create(String name) throws ParserConfigurationException, FactoryConfigurationError @@ -200,12 +200,12 @@ public static XMLBuilder create(String name) * {@link DocumentBuilderFactory} * @return * a builder node that can be used to add more nodes to the XML document. - * @throws ParserConfigurationException * - * @throws FactoryConfigurationError - * @throws ParserConfigurationException - * @throws IOException - * @throws SAXException + * @throws ParserConfigurationException xyz + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz + * @throws IOException xyz + * @throws SAXException xyz */ public static XMLBuilder parse( InputSource inputSource, boolean enableExternalEntities, @@ -232,11 +232,11 @@ public static XMLBuilder parse( * @return * a builder node that can be used to add more nodes to the XML document. * - * @throws ParserConfigurationException - * @throws FactoryConfigurationError - * @throws ParserConfigurationException - * @throws IOException - * @throws SAXException + * @throws ParserConfigurationException xyz + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz + * @throws IOException xyz + * @throws SAXException xyz */ public static XMLBuilder parse( String xmlString, boolean enableExternalEntities, @@ -264,11 +264,11 @@ public static XMLBuilder parse( * @return * a builder node that can be used to add more nodes to the XML document. * - * @throws ParserConfigurationException - * @throws FactoryConfigurationError - * @throws ParserConfigurationException - * @throws IOException - * @throws SAXException + * @throws ParserConfigurationException xyz + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz + * @throws IOException xyz + * @throws SAXException xyz */ public static XMLBuilder parse(File xmlFile, boolean enableExternalEntities, boolean isNamespaceAware) @@ -289,12 +289,12 @@ public static XMLBuilder parse(File xmlFile, boolean enableExternalEntities, * an XML document input source that will be parsed into a DOM. * @return * a builder node that can be used to add more nodes to the XML document. - * @throws ParserConfigurationException * - * @throws FactoryConfigurationError - * @throws ParserConfigurationException - * @throws IOException - * @throws SAXException + * @throws ParserConfigurationException xyz + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz + * @throws IOException xyz + * @throws SAXException xyz */ public static XMLBuilder parse(InputSource inputSource) throws ParserConfigurationException, SAXException, IOException @@ -312,11 +312,11 @@ public static XMLBuilder parse(InputSource inputSource) * @return * a builder node that can be used to add more nodes to the XML document. * - * @throws ParserConfigurationException - * @throws FactoryConfigurationError - * @throws ParserConfigurationException - * @throws IOException - * @throws SAXException + * @throws ParserConfigurationException xyz + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz + * @throws IOException xyz + * @throws SAXException xyz */ public static XMLBuilder parse(String xmlString) throws ParserConfigurationException, SAXException, IOException @@ -334,11 +334,11 @@ public static XMLBuilder parse(String xmlString) * @return * a builder node that can be used to add more nodes to the XML document. * - * @throws ParserConfigurationException - * @throws FactoryConfigurationError - * @throws ParserConfigurationException - * @throws IOException - * @throws SAXException + * @throws ParserConfigurationException xyz + * @throws FactoryConfigurationError xyz + * @throws ParserConfigurationException xyz + * @throws IOException xyz + * @throws SAXException xyz */ public static XMLBuilder parse(File xmlFile) throws ParserConfigurationException, SAXException, IOException diff --git a/src/main/java/com/jamesmurty/utils/XMLBuilder2.java b/src/main/java/com/jamesmurty/utils/XMLBuilder2.java index 96473d7..6f0cda6 100644 --- a/src/main/java/com/jamesmurty/utils/XMLBuilder2.java +++ b/src/main/java/com/jamesmurty/utils/XMLBuilder2.java @@ -1,5 +1,5 @@ /* - * Copyright 2008-2017 James Murty (www.jamesmurty.com) + * Copyright 2008-2020 James Murty (github.com/jmurty) * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. diff --git a/src/test/java/com/jamesmurty/utils/BaseXMLBuilderTests.java b/src/test/java/com/jamesmurty/utils/BaseXMLBuilderTests.java index ca8876f..274d461 100644 --- a/src/test/java/com/jamesmurty/utils/BaseXMLBuilderTests.java +++ b/src/test/java/com/jamesmurty/utils/BaseXMLBuilderTests.java @@ -6,7 +6,6 @@ import java.io.StringWriter; import java.util.Properties; -import javax.annotation.Resource; import javax.xml.transform.OutputKeys; import javax.xml.xpath.XPathConstants; import javax.xml.xpath.XPathExpressionException;