#287: Add javadoc comments for specobject parser

itsallcode · Jul 14, 2021 · bb18abf · bb18abf
1 parent 4652edf
commit bb18abf
Show file tree

Hide file tree

Showing 23 changed files with 336 additions and 42 deletions.
diff --git a/...main/java/org/itsallcode/openfasttrace/importer/specobject/SpecobjectImporterFactory.java b/...main/java/org/itsallcode/openfasttrace/importer/specobject/SpecobjectImporterFactory.java
@@ -35,6 +35,9 @@ public class SpecobjectImporterFactory extends RegexMatchingImporterFactory
 {
     private final SAXParserFactory saxParserFactory;
 
+    /**
+     * Create a new instance.
+     */
     public SpecobjectImporterFactory()
     {
         super("(?i).*\\.(xml|oreqm)");

diff --git a/.../org/itsallcode/openfasttrace/importer/specobject/handler/DependenciesHandlerBuilder.java b/.../org/itsallcode/openfasttrace/importer/specobject/handler/DependenciesHandlerBuilder.java
@@ -27,18 +27,18 @@
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.CallbackContentHandler;
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.TreeContentHandler;
 
-public class DependenciesHandlerBuilder
+class DependenciesHandlerBuilder
 {
     private final ImportEventListener listener;
     private final CallbackContentHandler handler;
 
-    public DependenciesHandlerBuilder(final ImportEventListener listener)
+    DependenciesHandlerBuilder(final ImportEventListener listener)
     {
         this.listener = listener;
         this.handler = new CallbackContentHandler();
     }
 
-    public TreeContentHandler build()
+    TreeContentHandler build()
     {
         this.handler.addCharacterDataListener("dependson",
                 data -> this.listener.addDependsOnId(SpecificationItemId.parseId(data)));

diff --git a/...a/org/itsallcode/openfasttrace/importer/specobject/handler/FulfilledByHandlerBuilder.java b/...a/org/itsallcode/openfasttrace/importer/specobject/handler/FulfilledByHandlerBuilder.java
@@ -25,24 +25,24 @@
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.CallbackContentHandler;
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.TreeContentHandler;
 
-public class FulfilledByHandlerBuilder
+class FulfilledByHandlerBuilder
 {
     private final CallbackContentHandler handler;
 
-    public FulfilledByHandlerBuilder()
+    FulfilledByHandlerBuilder()
     {
         this.handler = new CallbackContentHandler();
     }
 
-    public TreeContentHandler build()
+    TreeContentHandler build()
     {
         this.handler.addSubTreeHandler("ffbObj", this::createFulfillByObjectHandler);
         return this.handler;
     }
 
     private CallbackContentHandler createFulfillByObjectHandler()
     {
-        return new CallbackContentHandler() //
+        return new CallbackContentHandler()
                 .addCharacterDataListener("ffbId", data -> {})
                 .addCharacterDataListener("ffbType", data -> {})
                 .addIntDataListener("ffbVersion", data -> {});

diff --git a/...org/itsallcode/openfasttrace/importer/specobject/handler/NeedsCoverageHandlerBuilder.java b/...org/itsallcode/openfasttrace/importer/specobject/handler/NeedsCoverageHandlerBuilder.java
@@ -26,18 +26,18 @@
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.CallbackContentHandler;
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.TreeContentHandler;
 
-public class NeedsCoverageHandlerBuilder
+class NeedsCoverageHandlerBuilder
 {
     private final ImportEventListener listener;
     private final CallbackContentHandler handler;
 
-    public NeedsCoverageHandlerBuilder(final ImportEventListener listener)
+    NeedsCoverageHandlerBuilder(final ImportEventListener listener)
     {
         this.listener = listener;
         this.handler = new CallbackContentHandler();
     }
 
-    public TreeContentHandler build()
+    TreeContentHandler build()
     {
         return this.handler.addCharacterDataListener("needsobj",
                 this.listener::addNeededArtifactType);

diff --git a/.../itsallcode/openfasttrace/importer/specobject/handler/ProvidesCoverageHandlerBuilder.java b/.../itsallcode/openfasttrace/importer/specobject/handler/ProvidesCoverageHandlerBuilder.java
@@ -27,19 +27,19 @@
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.CallbackContentHandler;
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.TreeContentHandler;
 
-public class ProvidesCoverageHandlerBuilder
+class ProvidesCoverageHandlerBuilder
 {
     private final ImportEventListener listener;
     private final CallbackContentHandler handler;
     private Builder providesCoverageIdBuilder;
 
-    public ProvidesCoverageHandlerBuilder(final ImportEventListener listener)
+    ProvidesCoverageHandlerBuilder(final ImportEventListener listener)
     {
         this.listener = listener;
         this.handler = new CallbackContentHandler();
     }
 
-    public TreeContentHandler build()
+    TreeContentHandler build()
     {
         this.handler.addElementListener("provcov",
                 elem -> this.providesCoverageIdBuilder = new Builder(), //

diff --git a/...itsallcode/openfasttrace/importer/specobject/handler/SingleSpecObjectsHandlerBuilder.java b/...itsallcode/openfasttrace/importer/specobject/handler/SingleSpecObjectsHandlerBuilder.java
@@ -28,7 +28,7 @@
 import org.itsallcode.openfasttrace.api.importer.ImportEventListener;
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.CallbackContentHandler;
 
-public class SingleSpecObjectsHandlerBuilder
+class SingleSpecObjectsHandlerBuilder
 {
     private final CallbackContentHandler handler;
     private final ImportEventListener listener;
@@ -37,7 +37,7 @@ public class SingleSpecObjectsHandlerBuilder
     private String containedFileName = null;
     private int containedLine = -1;
 
-    public SingleSpecObjectsHandlerBuilder(final ImportEventListener listener,
+    SingleSpecObjectsHandlerBuilder(final ImportEventListener listener,
             final SpecificationItemId.Builder idBuilder, final Location.Builder locationBuilder)
     {
         this.listener = listener;
@@ -46,7 +46,7 @@ public SingleSpecObjectsHandlerBuilder(final ImportEventListener listener,
         this.handler = new CallbackContentHandler();
     }
 
-    public CallbackContentHandler build()
+    CallbackContentHandler build()
     {
         configureDataHandlers();
         configureSubTreeHanlders();

diff --git a/.../org/itsallcode/openfasttrace/importer/specobject/handler/SpecDocumentHandlerBuilder.java b/.../org/itsallcode/openfasttrace/importer/specobject/handler/SpecDocumentHandlerBuilder.java
@@ -31,6 +31,9 @@
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.CallbackContentHandler;
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.TreeContentHandler;
 
+/**
+ * Register handlers for parsing an XML specobject document.
+ */
 public class SpecDocumentHandlerBuilder
 {
     private static final Logger LOG = Logger.getLogger(SpecDocumentHandlerBuilder.class.getName());
@@ -40,13 +43,26 @@ public class SpecDocumentHandlerBuilder
     private final InputFile file;
     private final ImportEventListener listener;
 
+    /**
+     * Create a new instance.
+     * 
+     * @param file
+     *            the parsed input file.
+     * @param listener
+     *            the listener receiving import events.
+     */
     public SpecDocumentHandlerBuilder(final InputFile file, final ImportEventListener listener)
     {
         this.file = file;
         this.listener = listener;
         this.handler = new CallbackContentHandler();
     }
 
+    /**
+     * Build the handler.
+     * 
+     * @return the content handler.
+     */
     public TreeContentHandler build()
     {
         this.handler.setDefaultStartElementListener(startElement -> {

diff --git a/...a/org/itsallcode/openfasttrace/importer/specobject/handler/SpecObjectsHandlerBuilder.java b/...a/org/itsallcode/openfasttrace/importer/specobject/handler/SpecObjectsHandlerBuilder.java
@@ -30,7 +30,7 @@
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.CallbackContentHandler;
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.TreeElement;
 
-public class SpecObjectsHandlerBuilder
+class SpecObjectsHandlerBuilder
 {
     private final CallbackContentHandler handler;
     private final InputFile file;
@@ -40,7 +40,7 @@ public class SpecObjectsHandlerBuilder
     private final String defaultDoctype;
     private Location.Builder locationBuilder;
 
-    public SpecObjectsHandlerBuilder(final InputFile file, final String defaultDoctype,
+    SpecObjectsHandlerBuilder(final InputFile file, final String defaultDoctype,
             final ImportEventListener listener)
     {
         this.file = file;
@@ -49,7 +49,7 @@ public SpecObjectsHandlerBuilder(final InputFile file, final String defaultDocty
         this.handler = new CallbackContentHandler();
     }
 
-    public CallbackContentHandler build()
+    CallbackContentHandler build()
     {
         this.handler.addElementListener("specobject", this::handleStartElement,
                 endElement -> handleEndElement());

diff --git a/...ain/java/org/itsallcode/openfasttrace/importer/specobject/handler/TagsHandlerBuilder.java b/...ain/java/org/itsallcode/openfasttrace/importer/specobject/handler/TagsHandlerBuilder.java
@@ -26,18 +26,18 @@
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.CallbackContentHandler;
 import org.itsallcode.openfasttrace.importer.specobject.xml.tree.TreeContentHandler;
 
-public class TagsHandlerBuilder
+class TagsHandlerBuilder
 {
     private final ImportEventListener listener;
     private final CallbackContentHandler handler;
 
-    public TagsHandlerBuilder(final ImportEventListener listener)
+    TagsHandlerBuilder(final ImportEventListener listener)
     {
         this.listener = listener;
         this.handler = new CallbackContentHandler();
     }
 
-    public TreeContentHandler build()
+    TreeContentHandler build()
     {
         return this.handler.addCharacterDataListener("tag", this.listener::addTag);
     }

diff --git a/...main/java/org/itsallcode/openfasttrace/importer/specobject/xml/ContentHandlerAdapter.java b/...main/java/org/itsallcode/openfasttrace/importer/specobject/xml/ContentHandlerAdapter.java
@@ -30,24 +30,42 @@
 import org.xml.sax.*;
 import org.xml.sax.helpers.DefaultHandler;
 
+/**
+ * A SAX content handler that forwards events from an {@link XMLReader} a
+ * {@link EventContentHandler}.
+ */
 public class ContentHandlerAdapter extends DefaultHandler implements ContentHandlerAdapterController
 {
     private static final Logger LOG = Logger.getLogger(ContentHandlerAdapter.class.getName());
 
-    private final String fileName;
+    private final String filePath;
     private final XMLReader xmlReader;
     private final EventContentHandler delegate;
     private Locator locator;
     private ContentHandler originalContentHandler;
 
-    public ContentHandlerAdapter(final String fileName, final XMLReader xmlReader,
+    /**
+     * Create a new instance.
+     * 
+     * @param filePath
+     *            the path of the parsed file.
+     * @param xmlReader
+     *            the {@link XMLReader}.
+     * @param delegate
+     *            the content handler to which the parsing events should be
+     *            forwared.
+     */
+    public ContentHandlerAdapter(final String filePath, final XMLReader xmlReader,
             final EventContentHandler delegate)
     {
-        this.fileName = fileName;
+        this.filePath = filePath;
         this.xmlReader = xmlReader;
         this.delegate = delegate;
     }
 
+    /**
+     * Initialize the delegate and register XML content handler.
+     */
     public void registerListener()
     {
         if (this.originalContentHandler != null)
@@ -89,7 +107,7 @@ public void endElement(final String uri, final String localName, final String qN
 
     private Location getCurrentLocation()
     {
-        return Location.create(this.fileName, this.locator.getLineNumber(),
+        return Location.create(this.filePath, this.locator.getLineNumber(),
                 this.locator.getColumnNumber());
     }
 

diff --git a/...org/itsallcode/openfasttrace/importer/specobject/xml/ContentHandlerAdapterController.java b/...org/itsallcode/openfasttrace/importer/specobject/xml/ContentHandlerAdapterController.java
@@ -22,7 +22,14 @@
  * #L%
  */
 
+/**
+ * A controller that allows finishing the parsing.
+ */
 public interface ContentHandlerAdapterController
 {
+    /**
+     * Tell the controller that this handler is finished with parsing the XML
+     * sub tree.
+     */
     void parsingFinished();
 }
diff --git a/...c/main/java/org/itsallcode/openfasttrace/importer/specobject/xml/EventContentHandler.java b/...c/main/java/org/itsallcode/openfasttrace/importer/specobject/xml/EventContentHandler.java
@@ -25,13 +25,40 @@
  * #L%
  */
 
+/**
+ * An event handler for XML parsing events.
+ */
 public interface EventContentHandler
 {
+    /**
+     * Called before parsing begins.
+     * 
+     * @param contentHandlerAdapter
+     *            the controller.
+     */
+    void init(ContentHandlerAdapterController contentHandlerAdapter);
+
+    /**
+     * Called when an XML element starts.
+     * 
+     * @param event
+     *            the start event.
+     */
     void startElement(StartElementEvent event);
 
+    /**
+     * Called when an XML element ends.
+     * 
+     * @param event
+     *            the end event.
+     */
     void endElement(EndElementEvent event);
 
+    /**
+     * Called when character data content is found.
+     * 
+     * @param characters
+     *            the character data.
+     */
     void characters(String characters);
-
-    void init(ContentHandlerAdapterController contentHandlerAdapter);
 }
diff --git a/...ain/java/org/itsallcode/openfasttrace/importer/specobject/xml/IgnoringEntityResolver.java b/...ain/java/org/itsallcode/openfasttrace/importer/specobject/xml/IgnoringEntityResolver.java
@@ -28,6 +28,9 @@
 import org.xml.sax.EntityResolver;
 import org.xml.sax.InputSource;
 
+/**
+ * An {@link EntityResolver} that ignores all entities.
+ */
 public class IgnoringEntityResolver implements EntityResolver
 {
     private static final Logger LOG = Logger.getLogger(IgnoringEntityResolver.class.getName());

diff --git a/...main/java/org/itsallcode/openfasttrace/importer/specobject/xml/SaxParserConfigurator.java b/...main/java/org/itsallcode/openfasttrace/importer/specobject/xml/SaxParserConfigurator.java
@@ -30,12 +30,20 @@
 import org.xml.sax.SAXNotRecognizedException;
 import org.xml.sax.SAXNotSupportedException;
 
+/**
+ * Configures a SAX parser.
+ */
 public class SaxParserConfigurator
 {
     private SaxParserConfigurator()
     {
     }
 
+    /**
+     * Creates a new {@link SAXParserFactory} for secure processing.
+     * 
+     * @return the configured factory.
+     */
     public static SAXParserFactory createSaxParserFactory()
     {
         final SAXParserFactory parserFactory = SAXParserFactory.newInstance();