This is an automated email from the ASF dual-hosted git repository.
slawrence pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-daffodil.git
The following commit(s) were added to refs/heads/master by this push:
new 853a5f2 Support all LTS and one non-LTS Java versions
853a5f2 is described below
commit 853a5f27ab2e4287b63dbad746a0e883ec67a2c7
Author: Steve Lawrence <[email protected]>
AuthorDate: Thu Nov 12 14:45:28 2020 -0500
Support all LTS and one non-LTS Java versions
- Drop support for Java 9 since it is no longer supported by upstream.
Now only support the two LTS versions (Java 8 and 11) and the latest
non-LTS version (Java 15)
- Javadoc versions newer than Java 12 are a bit more strict about some
aspects of Javadoc. Update the JAPI/SAPI documentation so that there
are no errors, and to minimze warnings. The genjavadoc plugin we use
to convert Scala code to Java API isn't perfect so we can't get rid of
all warnings. This is caused by missing constructor documentation that
doesn't convert from scaladoc to javadoc.
- Add the -quiet option to javadoc so it only shows if there are issues.
- Cleanup some javadocs that are inconsistent or lacking in
documentation
DAFFODIL-2463, DAFFODIL-2332
---
.github/workflows/main.yml | 2 +-
build.sbt | 3 +-
.../org/apache/daffodil/japi/ValidationMode.java | 3 ++
.../daffodil/japi/debugger/package-info.java | 2 +-
.../org/apache/daffodil/japi/logger/LogLevel.java | 7 ++-
.../apache/daffodil/japi/logger/package-info.java | 2 +-
.../org/apache/daffodil/japi/package-info.java | 14 ++---
.../scala/org/apache/daffodil/japi/Daffodil.scala | 33 ++++++++++--
.../org/apache/daffodil/japi/infoset/Infoset.scala | 62 +++++++++++++++++-----
.../japi/io/InputSourceDataInputStream.scala | 14 +++++
.../scala/org/apache/daffodil/sapi/Daffodil.scala | 27 +++++++++-
.../org/apache/daffodil/sapi/infoset/Infoset.scala | 62 +++++++++++++++++-----
.../sapi/io/InputSourceDataInputStream.scala | 14 +++++
.../udf/UserDefinedFunctionIdentification.java | 17 +++++-
.../UserDefinedFunctionFatalException.java | 11 ++++
.../UserDefinedFunctionProcessingError.java | 19 ++++++-
16 files changed, 248 insertions(+), 44 deletions(-)
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 57c80c1..12ae8c8 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -23,7 +23,7 @@ jobs:
strategy:
fail-fast: false
matrix:
- java_version: [ 8, 9, 11 ]
+ java_version: [ 8, 11, 15 ]
scala_version: [ 2.12.11 ]
os: [ 'ubuntu-latest', 'windows-latest' ]
env:
diff --git a/build.sbt b/build.sbt
index ded0a1f..5a3fdd5 100644
--- a/build.sbt
+++ b/build.sbt
@@ -251,7 +251,8 @@ lazy val unidocSettings = Seq(
javacOptions in (JavaUnidoc, unidoc) := Seq(
"-windowtitle", "Apache Daffodil (incubating) " + version.value + " Java
API",
"-doctitle", "<h1>Apache Daffodil (incubating) " + version.value + " Java
API</h1>",
- "-notimestamp"
+ "-notimestamp",
+ "-quiet",
),
unidocAllSources in (JavaUnidoc, unidoc) := (unidocAllSources in
(JavaUnidoc, unidoc)).value.map { sources =>
sources.filterNot { source =>
diff --git
a/daffodil-japi/src/main/java/org/apache/daffodil/japi/ValidationMode.java
b/daffodil-japi/src/main/java/org/apache/daffodil/japi/ValidationMode.java
index 6db5de5..c76d43a 100644
--- a/daffodil-japi/src/main/java/org/apache/daffodil/japi/ValidationMode.java
+++ b/daffodil-japi/src/main/java/org/apache/daffodil/japi/ValidationMode.java
@@ -36,6 +36,9 @@ public enum ValidationMode {
*/
Full(30);
+ /**
+ * Numeric ID of the validation mode
+ */
public final int id;
private ValidationMode(int id) {
diff --git
a/daffodil-japi/src/main/java/org/apache/daffodil/japi/debugger/package-info.java
b/daffodil-japi/src/main/java/org/apache/daffodil/japi/debugger/package-info.java
index fa91589..b3efb01 100644
---
a/daffodil-japi/src/main/java/org/apache/daffodil/japi/debugger/package-info.java
+++
b/daffodil-japi/src/main/java/org/apache/daffodil/japi/debugger/package-info.java
@@ -18,7 +18,7 @@
/**
* Provides the classes necessary to perform parse tracing or create a custom
debugger
*
- * <h3>Overview</h3>
+ * <h2>Overview</h2>
*
* Daffodil comes with one prebuilt debugger, the {@link
* org.apache.daffodil.japi.debugger.TraceDebuggerRunner}, which outputs
diff --git
a/daffodil-japi/src/main/java/org/apache/daffodil/japi/logger/LogLevel.java
b/daffodil-japi/src/main/java/org/apache/daffodil/japi/logger/LogLevel.java
index dd581ff..7e170f4 100644
--- a/daffodil-japi/src/main/java/org/apache/daffodil/japi/logger/LogLevel.java
+++ b/daffodil-japi/src/main/java/org/apache/daffodil/japi/logger/LogLevel.java
@@ -24,7 +24,6 @@ package org.apache.daffodil.japi.logger;
* <p>
* Levels Resolver Compile, Debug, and OOLAGDebug are intended for Daffodil
developer
* use.
- *
*/
public enum LogLevel {
Error(10),
@@ -36,8 +35,14 @@ public enum LogLevel {
OOLAGDebug(60),
DelimDebug(70);
+ /**
+ * Numeric ID of the log level
+ */
public final int id;
+ /**
+ * Create a LogLevel with a specified id
+ */
private LogLevel(int id) {
this.id = id;
}
diff --git
a/daffodil-japi/src/main/java/org/apache/daffodil/japi/logger/package-info.java
b/daffodil-japi/src/main/java/org/apache/daffodil/japi/logger/package-info.java
index aa75ca0..2d6b034 100644
---
a/daffodil-japi/src/main/java/org/apache/daffodil/japi/logger/package-info.java
+++
b/daffodil-japi/src/main/java/org/apache/daffodil/japi/logger/package-info.java
@@ -18,7 +18,7 @@
/**
* Provides the classes necessary to receive logging messages from Daffodil.
*
- * <h3>Overview</h3>
+ * <h2>Overview</h2>
*
* Daffodil comes with three prebuilt log writers:
* <ul>
diff --git
a/daffodil-japi/src/main/java/org/apache/daffodil/japi/package-info.java
b/daffodil-japi/src/main/java/org/apache/daffodil/japi/package-info.java
index 42c0fb3..2c00eb1 100644
--- a/daffodil-japi/src/main/java/org/apache/daffodil/japi/package-info.java
+++ b/daffodil-japi/src/main/java/org/apache/daffodil/japi/package-info.java
@@ -20,7 +20,7 @@
* unparse files using the compiled objects, and retrieve results and
* parsing diagnostics
*
- * <h3>Overview</h3>
+ * <h2>Overview</h2>
*
* The {@link org.apache.daffodil.japi.Daffodil} object is a factory object to
create a
* {@link org.apache.daffodil.japi.Compiler}. The {@link
org.apache.daffodil.japi.Compiler} provides
@@ -106,9 +106,9 @@
* {@link
org.apache.daffodil.japi.DaffodilUnparseContentHandler#getUnparseResult()} once
the
* XMLReader.parse run is complete.
*
- * <h4>Parse</h4>
+ * <h3>Parse</h3>
*
- * <h5>Dataprocessor Parse</h5>
+ * <h4>Dataprocessor Parse</h4>
*
* The {@link
org.apache.daffodil.japi.DataProcessor#parse(org.apache.daffodil.japi.io.InputSourceDataInputStream,
* org.apache.daffodil.japi.infoset.InfosetOutputter)} method accepts input
data to parse in the form
@@ -159,7 +159,7 @@
* }
* }</pre>
*
- * <h5>SAX Parse</h5>
+ * <h4>SAX Parse</h4>
* The {@link org.apache.daffodil.japi.DaffodilParseXMLReader#parse(
* org.apache.daffodil.japi.io.InputSourceDataInputStream)} method accepts
input data to parse in
* the form of a {@link
org.apache.daffodil.japi.io.InputSourceDataInputStream}. The output
@@ -219,9 +219,9 @@
* }
* </pre>
*
- * <h4>Unparse</h4>
+ * <h3>Unparse</h3>
*
- * <h5>Dataprocessor Unparse</h5>
+ * <h4>Dataprocessor Unparse</h4>
*
* The same {@link org.apache.daffodil.japi.DataProcessor} used for parse can
be used to unparse an
* infoset via the {@link
org.apache.daffodil.japi.DataProcessor#unparse(org.apache.daffodil.japi.infoset.InfosetInputter,
@@ -235,7 +235,7 @@
* UnparseResult ur = dp.unparse(jdomInputter, wbc)
* }</pre>
*
- * <h5>SAX Unparse</h5>
+ * <h4>SAX Unparse</h4>
*
* In order to kick off an unparse via the SAX API, one must register the
* {@link org.apache.daffodil.japi.DaffodilUnparseContentHandler} as the
contentHandler for an
diff --git
a/daffodil-japi/src/main/scala/org/apache/daffodil/japi/Daffodil.scala
b/daffodil-japi/src/main/scala/org/apache/daffodil/japi/Daffodil.scala
index a57f4e6..83918dc 100644
--- a/daffodil-japi/src/main/scala/org/apache/daffodil/japi/Daffodil.scala
+++ b/daffodil-japi/src/main/scala/org/apache/daffodil/japi/Daffodil.scala
@@ -379,7 +379,11 @@ class ProcessorFactory private[japi] (private var pf:
SProcessorFactory)
new DataProcessor(dp)
}
- class ExperimentalWrapper(val rootView: RootView)
+ /**
+ * Wrapper class used to mimic a Scala object namespacing experimental APIs
+ */
+ protected class ExperimentalWrapper(val rootView: RootView)
+
/**
* Exposes the RootView object corresponding to this ProcessorFactory. This
can
* be used to start a walk using the walkFromRoot method in a DSOM Walker.
@@ -464,12 +468,17 @@ class Diagnostic private[japi] (d: SDiagnostic) {
def isError = d.isError
/**
- * Positively get these things. No returning 'null' and making caller figure
out
- * whether to look for cause object.
+ * Get the cause of that cause this diagnostic
*
* @return the exception that caused the diagnostic
*/
def getSomeCause: Throwable = d.getSomeCause.get
+
+ /**
+ * Get the message that caused this diagnostic
+ *
+ * @return the message that caused the diagnostic
+ */
def getSomeMessage: String = d.getSomeMessage.get
}
@@ -489,7 +498,7 @@ class DataLocation private[japi] (dl: SDataLocation) {
/**
* Get the position of the data, in bits, using 1-based indexing
*
- * @return position of the data in bites
+ * @return position of the data in bits
*/
def bitPos1b() = dl.bitPos1b
@@ -883,9 +892,25 @@ class DaffodilUnhandledSAXException private[japi]
(exception: SDaffodilUnhandled
* The full URIs needed for setting/getting properties for the
[[DaffodilParseXMLReader]]
*/
object DaffodilParseXMLReader {
+
+ /**
+ * Property name to get the [[ParseResult]] from the
[[DaffodilParseXMLReader]]. This property is read only.
+ */
val DAFFODIL_SAX_URN_PARSERESULT: String =
XMLUtils.DAFFODIL_SAX_URN_PARSERESULT
+
+ /**
+ * Property name to get/set blob directory as String from the
[[DaffodilParseXMLReader]]
+ */
val DAFFODIL_SAX_URN_BLOBDIRECTORY: String =
XMLUtils.DAFFODIL_SAX_URN_BLOBDIRECTORY
+
+ /**
+ * Property name to get/set blob prefix as String from the
[[DaffodilParseXMLReader]]
+ */
val DAFFODIL_SAX_URN_BLOBPREFIX: String =
XMLUtils.DAFFODIL_SAX_URN_BLOBPREFIX
+
+ /**
+ * Property name to get/set blob suffix as String from the
[[DaffodilParseXMLReader]]
+ */
val DAFFODIL_SAX_URN_BLOBSUFFIX: String =
XMLUtils.DAFFODIL_SAX_URN_BLOBSUFFIX
}
diff --git
a/daffodil-japi/src/main/scala/org/apache/daffodil/japi/infoset/Infoset.scala
b/daffodil-japi/src/main/scala/org/apache/daffodil/japi/infoset/Infoset.scala
index 662f12c..ad6e612 100644
---
a/daffodil-japi/src/main/scala/org/apache/daffodil/japi/infoset/Infoset.scala
+++
b/daffodil-japi/src/main/scala/org/apache/daffodil/japi/infoset/Infoset.scala
@@ -205,7 +205,7 @@ abstract class InfosetOutputter extends SInfosetOutputter {
/**
- * Output the infoset as a scala.xml.Node
+ * [[InfosetOutputter]] to build an infoset represented as a scala.xml.Node
*
* @param showFormatInfo add additional properties to each scala.xml.Node for
debug purposes
*/
@@ -214,9 +214,17 @@ class ScalaXMLInfosetOutputter(showFormatInfo: Boolean =
false)
override val infosetOutputter = new SScalaXMLInfosetOutputter(showFormatInfo)
+ /**
+ * Get the scala.xml.Node representing the infoset created during a parse
+ *
+ * This function shuld only be called if ParseResult.isError() returns false
+ */
def getResult(): scala.xml.Node = infosetOutputter.getResult()
}
+/**
+ * [[InfosetOutputter]] to build an infoset represented as XML written to a
java.io.OutputStream
+ */
class XMLTextInfosetOutputter private (outputter: SXMLTextInfosetOutputter)
extends InfosetOutputterProxy {
@@ -252,6 +260,9 @@ class XMLTextInfosetOutputter private (outputter:
SXMLTextInfosetOutputter)
override val infosetOutputter = outputter
}
+/**
+ * [[InfosetOutputter]] to build an infoset represented as JSON written to a
java.io.OutputStream
+ */
class JsonInfosetOutputter private (outputter: SJsonInfosetOutputter)
extends InfosetOutputterProxy {
@@ -288,29 +299,40 @@ class JsonInfosetOutputter private (outputter:
SJsonInfosetOutputter)
}
/**
- * Output the infoset as a jdom Document
+ * [[InfosetOutputter]] to build an infoset represented as an
org.jdom2.Document
*/
class JDOMInfosetOutputter()
extends InfosetOutputterProxy {
override val infosetOutputter = new SJDOMInfosetOutputter()
+ /**
+ * Get the jdom Document representing the infoset created during a parse
+ *
+ * This function shuld only be called if ParseResult.isError() returns false
+ */
def getResult(): org.jdom2.Document = infosetOutputter.getResult()
}
/**
- * Output the infoset as a w3c Document
+ * [[InfosetOutputter]] to build an infoset represented as an
org.w3c.dom.Document
*/
class W3CDOMInfosetOutputter()
extends InfosetOutputterProxy {
override val infosetOutputter = new SW3CDOMInfosetOutputter()
+ /**
+ * Get the w3c Document representing the infoset created during a parse
+ *
+ * This function shuld only be called if ParseResult.isError() returns false
+ */
def getResult(): org.w3c.dom.Document = infosetOutputter.getResult()
}
/**
- * Ignore all infoset output
+ * [[InfosetOutputter]] that does not build an infoset represention, ignoring
+ * all [[InfosetOutputter]] events
*/
class NullInfosetOutputter()
extends InfosetOutputterProxy {
@@ -320,9 +342,9 @@ class NullInfosetOutputter()
/**
- * Read in an infoset in the form of a scala.xml.Node
+ * [[InfosetInputter]] to read an infoset represented as a scala.xml.Node
*
- * @param node the infoset in the form of a scala.xml.Node
+ * @param node the scala.xml.Node infoset
*/
class ScalaXMLInfosetInputter(node: scala.xml.Node)
extends InfosetInputterProxy {
@@ -330,6 +352,9 @@ class ScalaXMLInfosetInputter(node: scala.xml.Node)
override val infosetInputter = new SScalaXMLInfosetInputter(node)
}
+/**
+ * [[InfosetInputter]] to read an infoset represented as XML from a
java.io.InputStream
+ */
class XMLTextInfosetInputter private (inputter: SXMLTextInfosetInputter)
extends InfosetInputterProxy {
@@ -351,6 +376,9 @@ class XMLTextInfosetInputter private (inputter:
SXMLTextInfosetInputter)
override val infosetInputter = inputter
}
+/**
+ * [[InfosetInputter]] to read an infoset represented as JSON from a
java.io.InputStream
+ */
class JsonInfosetInputter private (inputter: SJsonInfosetInputter)
extends InfosetInputterProxy {
@@ -373,9 +401,9 @@ class JsonInfosetInputter private (inputter:
SJsonInfosetInputter)
}
/**
- * Read in an infoset in the form of a jdom2 Document
+ * [[InfosetInputter]] to read an infoset represented as an org.jdom2.Document
*
- * @param document the infoset in the form of a jdom2 Document
+ * @param document the org.jdom2.Document infoset
*/
class JDOMInfosetInputter(document: org.jdom2.Document)
extends InfosetInputterProxy {
@@ -384,9 +412,9 @@ class JDOMInfosetInputter(document: org.jdom2.Document)
}
/**
- * Read in an infoset in the form of a w3c Document
+ * [[InfosetInputter]] to read an infoset represented as an
org.w3c.dom.Document
*
- * @param document the infoset in the form of a w3c Document. Note that w3c
+ * @param document the org.w3c.dom.Document infoset. Note that w3c
* Documents are not guaranteed to be thread-safe, even if all
* users only read/traverse it. It is up to the user to ensure
* that the Document passed into the W3CDOMInfosetInputter is
@@ -399,9 +427,14 @@ class W3CDOMInfosetInputter(document: org.w3c.dom.Document)
override val infosetInputter = new SW3CDOMInfosetInputter(document)
}
-/* A proxy for existing infoset inputters */
+/**
+ * A proxy for InfosetInputters that are internal to Daffodil
+ */
abstract class InfosetInputterProxy extends InfosetInputter {
+ /**
+ * The InfosetInputter to proxy infoset events to
+ */
protected val infosetInputter: SInfosetInputter
override def getEventType() = infosetInputter.getEventType()
@@ -416,9 +449,14 @@ abstract class InfosetInputterProxy extends
InfosetInputter {
override def fini = infosetInputter.fini
}
-/* A proxy for existing infoset outputters */
+/**
+ * A proxy for InfosetOutputters that are internal to Daffodil
+ */
abstract class InfosetOutputterProxy extends InfosetOutputter {
+ /**
+ * The InfosetOutputter to proxy infoset events to
+ */
protected val infosetOutputter: SInfosetOutputter
override def reset(): Unit = infosetOutputter.reset()
diff --git
a/daffodil-japi/src/main/scala/org/apache/daffodil/japi/io/InputSourceDataInputStream.scala
b/daffodil-japi/src/main/scala/org/apache/daffodil/japi/io/InputSourceDataInputStream.scala
index cbf0fce..76984a5 100644
---
a/daffodil-japi/src/main/scala/org/apache/daffodil/japi/io/InputSourceDataInputStream.scala
+++
b/daffodil-japi/src/main/scala/org/apache/daffodil/japi/io/InputSourceDataInputStream.scala
@@ -25,9 +25,23 @@ import org.apache.daffodil.io.{ InputSourceDataInputStream
=> SInputSourceDataIn
/**
* Provides Daffodil with byte data from an InputStream, ByteBuffer, or byte
* Array.
+ *
+ * @param dis the underlying Scala InputSourceDataInputStream
*/
class InputSourceDataInputStream private[japi] (private [japi] val dis:
SInputSourceDataInputStream) {
+
+ /**
+ * Create an InputSourceDataInputStream from a java.io.InputStream
+ */
def this(is: InputStream) = this(SInputSourceDataInputStream(is))
+
+ /**
+ * Create an InputSourceDataInputStream from a java.nio.ByteBuffer
+ */
def this(bb: ByteBuffer) = this(SInputSourceDataInputStream(bb))
+
+ /**
+ * Create an InputSourceDataInputStream from a byte array
+ */
def this(arr: Array[Byte]) = this(SInputSourceDataInputStream(arr))
}
diff --git
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/Daffodil.scala
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/Daffodil.scala
index 0d54ded..384ca29 100644
--- a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/Daffodil.scala
+++ b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/Daffodil.scala
@@ -434,10 +434,17 @@ class Diagnostic private[sapi] (d: SDiagnostic) {
def isError = d.isError
/**
- * Positively get these things. No returning 'null' and making caller figure
out
- * whether to look for cause object.
+ * Get the cause of that cause this diagnostic
+ *
+ * @return the exception that caused the diagnostic
*/
def getSomeCause: Throwable = d.getSomeCause.get
+
+ /**
+ * Get the message that caused this diagnostic
+ *
+ * @return the message that caused the diagnostic
+ */
def getSomeMessage: String = d.getSomeMessage.get
}
@@ -831,9 +838,25 @@ class DaffodilUnhandledSAXException private[sapi]
(exception: SDaffodilUnhandled
* The full URIs needed for setting/getting properties for the
[[DaffodilParseXMLReader]]
*/
object DaffodilParseXMLReader {
+
+ /**
+ * Property name to get the [[ParseResult]] from the
[[DaffodilParseXMLReader]]. This property is read only.
+ */
val DAFFODIL_SAX_URN_PARSERESULT: String =
XMLUtils.DAFFODIL_SAX_URN_PARSERESULT
+
+ /**
+ * Property name to get/set blob directory as String from the
[[DaffodilParseXMLReader]]
+ */
val DAFFODIL_SAX_URN_BLOBDIRECTORY: String =
XMLUtils.DAFFODIL_SAX_URN_BLOBDIRECTORY
+
+ /**
+ * Property name to get/set blob prefix as String from the
[[DaffodilParseXMLReader]]
+ */
val DAFFODIL_SAX_URN_BLOBPREFIX: String =
XMLUtils.DAFFODIL_SAX_URN_BLOBPREFIX
+
+ /**
+ * Property name to get/set blob suffix as String from the
[[DaffodilParseXMLReader]]
+ */
val DAFFODIL_SAX_URN_BLOBSUFFIX: String =
XMLUtils.DAFFODIL_SAX_URN_BLOBSUFFIX
}
diff --git
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/Infoset.scala
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/Infoset.scala
index 719a591..3615329 100644
---
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/Infoset.scala
+++
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/infoset/Infoset.scala
@@ -205,7 +205,7 @@ abstract class InfosetOutputter extends SInfosetOutputter {
/**
- * Output the infoset as a scala.xml.Node
+ * [[InfosetOutputter]] to build an infoset represented as a scala.xml.Node
*
* @param showFormatInfo add additional properties to each scala.xml.Node for
debug purposes
*/
@@ -214,9 +214,17 @@ class ScalaXMLInfosetOutputter(showFormatInfo: Boolean =
false)
override val infosetOutputter = new SScalaXMLInfosetOutputter(showFormatInfo)
+ /**
+ * Get the scala.xml.Node representing the infoset created during a parse
+ *
+ * This function shuld only be called if ParseResult.isError() returns false
+ */
def getResult(): scala.xml.Node = infosetOutputter.getResult()
}
+/**
+ * [[InfosetOutputter]] to build an infoset represented as XML written to a
java.io.OutputStream
+ */
class XMLTextInfosetOutputter private (outputter: SXMLTextInfosetOutputter)
extends InfosetOutputterProxy {
@@ -252,6 +260,9 @@ class XMLTextInfosetOutputter private (outputter:
SXMLTextInfosetOutputter)
override val infosetOutputter = outputter
}
+/**
+ * [[InfosetOutputter]] to build an infoset represented as JSON written to a
java.io.OutputStream
+ */
class JsonInfosetOutputter private (outputter: SJsonInfosetOutputter)
extends InfosetOutputterProxy {
@@ -288,29 +299,40 @@ class JsonInfosetOutputter private (outputter:
SJsonInfosetOutputter)
}
/**
- * Output the infoset as a jdom Document
+ * [[InfosetOutputter]] to build an infoset represented as an
org.jdom2.Document
*/
class JDOMInfosetOutputter()
extends InfosetOutputterProxy {
override val infosetOutputter = new SJDOMInfosetOutputter()
+ /**
+ * Get the jdom Document representing the infoset created during a parse
+ *
+ * This function shuld only be called if ParseResult.isError() returns false
+ */
def getResult(): org.jdom2.Document = infosetOutputter.getResult()
}
/**
- * Output the infoset as a w3c Document
+ * [[InfosetOutputter]] to build an infoset represented as an
org.w3c.dom.Document
*/
class W3CDOMInfosetOutputter()
extends InfosetOutputterProxy {
override val infosetOutputter = new SW3CDOMInfosetOutputter()
+ /**
+ * Get the w3c Document representing the infoset created during a parse
+ *
+ * This function shuld only be called if ParseResult.isError() returns false
+ */
def getResult(): org.w3c.dom.Document = infosetOutputter.getResult()
}
/**
- * Ignore all infoset output
+ * [[InfosetOutputter]] that does not build an infoset represention, ignoring
+ * all [[InfosetOutputter]] events
*/
class NullInfosetOutputter()
extends InfosetOutputterProxy {
@@ -320,9 +342,9 @@ class NullInfosetOutputter()
/**
- * Read in an infoset in the form of a scala.xml.Node
+ * [[InfosetInputter]] to read an infoset represented as a scala.xml.Node
*
- * @param node the infoset in the form of a scala.xml.Node
+ * @param node the scala.xml.Node infoset
*/
class ScalaXMLInfosetInputter(node: scala.xml.Node)
extends InfosetInputterProxy {
@@ -330,6 +352,9 @@ class ScalaXMLInfosetInputter(node: scala.xml.Node)
override val infosetInputter = new SScalaXMLInfosetInputter(node)
}
+/**
+ * [[InfosetInputter]] to read an infoset represented as XML from a
java.io.InputStream
+ */
class XMLTextInfosetInputter private (inputter: SXMLTextInfosetInputter)
extends InfosetInputterProxy {
@@ -351,6 +376,9 @@ class XMLTextInfosetInputter private (inputter:
SXMLTextInfosetInputter)
override val infosetInputter = inputter
}
+/**
+ * [[InfosetInputter]] to read an infoset represented as JSON from a
java.io.InputStream
+ */
class JsonInfosetInputter private (inputter: SJsonInfosetInputter)
extends InfosetInputterProxy {
@@ -373,9 +401,9 @@ class JsonInfosetInputter private (inputter:
SJsonInfosetInputter)
}
/**
- * Read in an infoset in the form of a jdom2 Document
+ * [[InfosetInputter]] to read an infoset represented as an org.jdom2.Document
*
- * @param document the infoset in the form of a jdom2 Document
+ * @param document the org.jdom2.Document infoset
*/
class JDOMInfosetInputter(document: org.jdom2.Document)
extends InfosetInputterProxy {
@@ -384,9 +412,9 @@ class JDOMInfosetInputter(document: org.jdom2.Document)
}
/**
- * Read in an infoset in the form of a w3c Document
+ * [[InfosetInputter]] to read an infoset represented as an
org.w3c.dom.Document
*
- * @param document the infoset in the form of a w3c Document. Note that w3c
+ * @param document the org.w3c.dom.Document infoset. Note that w3c
* Documents are not guaranteed to be thread-safe, even if all
* users only read/traverse it. It is up to the user to ensure
* that the Document passed into the W3CDOMInfosetInputter is
@@ -399,9 +427,14 @@ class W3CDOMInfosetInputter(document: org.w3c.dom.Document)
override val infosetInputter = new SW3CDOMInfosetInputter(document)
}
-/* A proxy for existing infoset inputters */
+/**
+ * A proxy for InfosetInputters that are internal to Daffodil
+ */
abstract class InfosetInputterProxy extends InfosetInputter {
+ /**
+ * The InfosetInputter to proxy infoset events to
+ */
protected val infosetInputter: SInfosetInputter
override def getEventType() = infosetInputter.getEventType()
@@ -416,9 +449,14 @@ abstract class InfosetInputterProxy extends
InfosetInputter {
override def fini = infosetInputter.fini
}
-/* A proxy for existing infoset outputters */
+/**
+ * A proxy for InfosetOutputters that are internal to Daffodil
+ */
abstract class InfosetOutputterProxy extends InfosetOutputter {
+ /**
+ * The InfosetOutputter to proxy infoset events to
+ */
protected val infosetOutputter: SInfosetOutputter
override def reset(): Unit = infosetOutputter.reset()
diff --git
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/io/InputSourceDataInputStream.scala
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/io/InputSourceDataInputStream.scala
index d32e172..f6f4fc1 100644
---
a/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/io/InputSourceDataInputStream.scala
+++
b/daffodil-sapi/src/main/scala/org/apache/daffodil/sapi/io/InputSourceDataInputStream.scala
@@ -25,9 +25,23 @@ import org.apache.daffodil.io.{ InputSourceDataInputStream
=> SInputSourceDataIn
/**
* Provides Daffodil with byte data from an InputStream, ByteBuffer, or byte
* Array.
+ *
+ * @param dis the underlying Scala InputSourceDataInputStream
*/
class InputSourceDataInputStream private[sapi] (private [sapi] val dis:
SInputSourceDataInputStream) {
+
+ /**
+ * Create an InputSourceDataInputStream from a java.io.InputStream
+ */
def this(is: InputStream) = this(SInputSourceDataInputStream(is))
+
+ /**
+ * Create an InputSourceDataInputStream from a java.nio.ByteBuffer
+ */
def this(bb: ByteBuffer) = this(SInputSourceDataInputStream(bb))
+
+ /**
+ * Create an InputSourceDataInputStream from a byte array
+ */
def this(arr: Array[Byte]) = this(SInputSourceDataInputStream(arr))
}
diff --git
a/daffodil-udf/src/main/java/org/apache/daffodil/udf/UserDefinedFunctionIdentification.java
b/daffodil-udf/src/main/java/org/apache/daffodil/udf/UserDefinedFunctionIdentification.java
index dfc15e6..30b967c 100644
---
a/daffodil-udf/src/main/java/org/apache/daffodil/udf/UserDefinedFunctionIdentification.java
+++
b/daffodil-udf/src/main/java/org/apache/daffodil/udf/UserDefinedFunctionIdentification.java
@@ -28,11 +28,26 @@ import java.lang.annotation.Target;
*
* It must have the name and namespaceURI fields initialized with the namespace
* and name callers would be expected to use in the schema.
- *
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface UserDefinedFunctionIdentification {
+
+ /**
+ * Get the local name that identifies the user defined function
+ *
+ * This value must be a valid XML NCName. It should not include a namespace
or namespace prefix.
+ *
+ * @return the value
+ */
String name();
+
+ /**
+ * Get the namespace URI that identifies the user defined function
+ *
+ * This value must be a valid XML anyURI.
+ *
+ * @return the value
+ */
String namespaceURI();
}
diff --git
a/daffodil-udf/src/main/java/org/apache/daffodil/udf/exceptions/UserDefinedFunctionFatalException.java
b/daffodil-udf/src/main/java/org/apache/daffodil/udf/exceptions/UserDefinedFunctionFatalException.java
index d5c6bc5..4aa0ac8 100644
---
a/daffodil-udf/src/main/java/org/apache/daffodil/udf/exceptions/UserDefinedFunctionFatalException.java
+++
b/daffodil-udf/src/main/java/org/apache/daffodil/udf/exceptions/UserDefinedFunctionFatalException.java
@@ -22,10 +22,21 @@ package org.apache.daffodil.udf.exceptions;
*/
@SuppressWarnings("serial")
public class UserDefinedFunctionFatalException extends Exception {
+
+ /**
+ * Constructs a new exception with a specified detail message
+ *
+ * @param errorMessage the detail message
+ */
public UserDefinedFunctionFatalException(String errorMessage) {
super(errorMessage);
}
+ /**
+ * Constructs a new exception with a specified cause
+ *
+ * @param cause the cause of the exception
+ */
public UserDefinedFunctionFatalException(Throwable cause) {
super(cause);
}
diff --git
a/daffodil-udf/src/main/java/org/apache/daffodil/udf/exceptions/UserDefinedFunctionProcessingError.java
b/daffodil-udf/src/main/java/org/apache/daffodil/udf/exceptions/UserDefinedFunctionProcessingError.java
index 5dfd7b8..411e226 100644
---
a/daffodil-udf/src/main/java/org/apache/daffodil/udf/exceptions/UserDefinedFunctionProcessingError.java
+++
b/daffodil-udf/src/main/java/org/apache/daffodil/udf/exceptions/UserDefinedFunctionProcessingError.java
@@ -22,15 +22,32 @@ package org.apache.daffodil.udf.exceptions;
*/
@SuppressWarnings("serial")
public class UserDefinedFunctionProcessingError extends Exception {
+
+ /**
+ * Constructs a new exception with a specified detail message
+ *
+ * @param errorMessage the detail message
+ */
public UserDefinedFunctionProcessingError(String errorMessage) {
super(errorMessage);
}
+ /**
+ * Constructs a new exception with a specified cause
+ *
+ * @param cause the cause of the exception
+ */
public UserDefinedFunctionProcessingError(Throwable cause) {
super(cause);
}
+ /**
+ * Constructs a new exception with a specified detail message and cause
+ *
+ * @param errorMessage the detail message
+ * @param cause the cause of the exception
+ */
public UserDefinedFunctionProcessingError(String errorMessage, Throwable
cause) {
super(errorMessage, cause);
}
-}
\ No newline at end of file
+}
