+ * This class handles the boilerplate requirements of the {@link XMLReader} interface, + * such as storing handler references and managing standard features/properties. + * Subclasses only need to implement the specific {@link #parse(InputSource)} logic. + *
+ */ +public abstract class AbstractXMLReader implements XMLReader { + + /** The ContentHandler to receive SAX events. */ + protected ContentHandler contentHandler; + + /** The ErrorHandler to receive error notifications. */ + protected ErrorHandler errorHandler; + + /** The DTDHandler to receive DTD events (rarely used for data types). */ + protected DTDHandler dtdHandler; + + /** The EntityResolver to resolve external entities. */ + protected EntityResolver entityResolver; + + /** Reusable instance that is cleared on each call of the accessor */ + private final AttributesImpl emptyAttributes = new AttributesImpl(); + + /** + * Helper method for subclasses to ensure the ContentHandler is configured. + *+ * Subclasses should call this at the beginning of their {@code parse} method. + *
+ * + * @throws SAXException if the ContentHandler has not been set. + */ + protected void ensureHandlerSet() throws SAXException { + if (contentHandler == null) { + throw new SAXException("ContentHandler not set"); + } + } + + /** + * Helper method for subclasses to get an empty instance of {@link AttributesImpl}. + *+ * This method reuses the same instance of {@link AttributesImpl} and clears it + * before use. + *
+ * + * @return An empty instance of {@link AttributesImpl} + */ + protected AttributesImpl getEmptyAttributes() { + emptyAttributes.clear(); + return emptyAttributes; + } + + /** + * Parse an XML document from the given input source. + *+ * Subclasses must implement this method to translate their specific data format + * into SAX events on the {@code contentHandler}. + *
+ * + * @param input The input source for the top-level of the XML document. + * @throws IOException If an I/O error occurs. + * @throws SAXException If any SAX errors occur during processing. + */ + @Override + public abstract void parse(InputSource input) throws IOException, SAXException; + + /** + * Parse an XML document from a system identifier (URI). + *+ * This implementation delegates to {@link #parse(InputSource)}. + *
+ * + * @param systemId The system identifier (URI). + * @throws IOException If an I/O error occurs. + * @throws SAXException If any SAX errors occur during processing. + */ + @Override + public void parse(String systemId) throws IOException, SAXException { + parse(new InputSource(systemId)); + } + + // --------------------------------------------------------- + // Standard Handler Getters/Setters + // --------------------------------------------------------- + + /** + * Return the current content handler. + * + * @return The current content handler, or null if none has been registered. + */ + @Override + public ContentHandler getContentHandler() { + return contentHandler; + } + + /** + * Allow an application to register a content event handler. + * + * @param handler The content handler. + */ + @Override + public void setContentHandler(ContentHandler handler) { + this.contentHandler = handler; + } + + /** + * Return the current error handler. + * + * @return The current error handler, or null if none has been registered. + */ + @Override + public ErrorHandler getErrorHandler() { + return errorHandler; + } + + /** + * Allow an application to register an error event handler. + * + * @param handler The error handler. + */ + @Override + public void setErrorHandler(ErrorHandler handler) { + this.errorHandler = handler; + } + + /** + * Return the current DTD handler. + * + * @return The current DTD handler, or null if none has been registered. + */ + @Override + public DTDHandler getDTDHandler() { + return dtdHandler; + } + + /** + * Allow an application to register a DTD event handler. + * + * @param handler The DTD handler. + */ + @Override + public void setDTDHandler(DTDHandler handler) { + this.dtdHandler = handler; + } + + /** + * Return the current entity resolver. + * + * @return The current entity resolver, or null if none has been registered. + */ + @Override + public EntityResolver getEntityResolver() { + return entityResolver; + } + + /** + * Allow an application to register an entity resolver. + * + * @param resolver The entity resolver. + */ + @Override + public void setEntityResolver(EntityResolver resolver) { + this.entityResolver = resolver; + } + + // --------------------------------------------------------- + // Strict Feature/Property Compliance + // --------------------------------------------------------- + + /** + * Look up the value of a feature flag. + *+ * This implementation enforces mandatory SAX2 features: + *
+ * This implementation prevents modifying mandatory SAX2 features to ensure the parser + * functions correctly with downstream transformers. + *
+ * + * @param name The feature name, which is a fully-qualified URI. + * @param value The requested value of the feature (true or false). + * @throws SAXNotRecognizedException If the feature value can't be assigned or retrieved. + * @throws SAXNotSupportedException When the feature name is recognized but its + * value cannot be set to the requested value. + */ + @Override + public void setFeature(String name, boolean value) throws SAXNotRecognizedException, SAXNotSupportedException { + if ("http://xml.org/sax/features/namespaces".equals(name)) { + if (!value) { + throw new SAXNotSupportedException("Cannot disable 'namespaces' feature for this parser"); + } + return; + } + else if ("http://xml.org/sax/features/namespace-prefixes".equals(name)) { + if (value) { + throw new SAXNotSupportedException("Cannot enable 'namespace-prefixes' feature for this parser"); + } + return; + } + throw new SAXNotRecognizedException("Feature not recognized: " + name); + } + + /** + * Look up the value of a property. + * + * @param name The property name, which is a fully-qualified URI. + * @return The current value of the property. + * @throws SAXNotRecognizedException If the property value can't be assigned or retrieved. + * @throws SAXNotSupportedException When the property name is recognized but its + * value cannot be determined at this time. + */ + @Override + public Object getProperty(String name) throws SAXNotRecognizedException, SAXNotSupportedException { + throw new SAXNotRecognizedException("Property not recognized: " + name); + } + + /** + * Set the value of a property. + * + * @param name The property name, which is a fully-qualified URI. + * @param value The requested value for the property. + * @throws SAXNotRecognizedException If the property value can't be assigned or retrieved. + * @throws SAXNotSupportedException When the property name is recognized but its + * value cannot be set to the requested value. + */ + @Override + public void setProperty(String name, Object value) throws SAXNotRecognizedException, SAXNotSupportedException { + throw new SAXNotRecognizedException("Property not recognized: " + name); + } +} diff --git a/server/test/org/openintegrationengine/engine/plugins/datatypes/AbstractXMLReaderTest.java b/server/test/org/openintegrationengine/engine/plugins/datatypes/AbstractXMLReaderTest.java new file mode 100644 index 0000000000..bff1664839 --- /dev/null +++ b/server/test/org/openintegrationengine/engine/plugins/datatypes/AbstractXMLReaderTest.java @@ -0,0 +1,234 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2025 Tony Germano + +package org.openintegrationengine.engine.plugins.datatypes; + +import static org.junit.Assert.assertFalse; +import static org.junit.Assert.assertNull; +import static org.junit.Assert.assertSame; +import static org.junit.Assert.assertTrue; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.eq; +import static org.mockito.Mockito.inOrder; +import static org.mockito.Mockito.mock; +import static org.mockito.Mockito.spy; +import static org.mockito.Mockito.verify; + +import java.io.IOException; + +import org.junit.Before; +import org.junit.Test; +import org.mockito.InOrder; +import org.xml.sax.Attributes; +import org.xml.sax.ContentHandler; +import org.xml.sax.DTDHandler; +import org.xml.sax.EntityResolver; +import org.xml.sax.ErrorHandler; +import org.xml.sax.InputSource; +import org.xml.sax.SAXException; +import org.xml.sax.SAXNotRecognizedException; +import org.xml.sax.SAXNotSupportedException; + +public class AbstractXMLReaderTest { + + private AbstractXMLReader reader; + + @Before + public void setUp() { + reader = new TestXMLReader(); + } + + // --------------------------------------------------------- + // Parsing Logic Tests + // --------------------------------------------------------- + + @Test + public void testParseEmitsSaxEvents() throws Exception { + // Mock the ContentHandler to verify events + ContentHandler handler = mock(ContentHandler.class); + reader.setContentHandler(handler); + + // Execute parse + reader.parse(new InputSource()); + + // Verify the exact sequence of SAX events was fired + InOrder inOrder = inOrder(handler); + inOrder.verify(handler).startDocument(); + inOrder.verify(handler).startElement(eq(""), eq("test"), eq(""), any(Attributes.class)); + inOrder.verify(handler).characters(eq("value".toCharArray()), eq(0), eq(5)); + inOrder.verify(handler).endElement(eq(""), eq("test"), eq("")); + inOrder.verify(handler).endDocument(); + } + + @Test + public void testParseStringDelegatesToInputSource() throws IOException, SAXException { + // Spy on the reader to verify method calls + AbstractXMLReader spyReader = spy(new TestXMLReader()); + String testUri = "file:///test.xml"; + + // Set a dummy handler so ensuringHandlerSet doesn't fail + spyReader.setContentHandler(mock(ContentHandler.class)); + + spyReader.parse(testUri); + + // Verify that parse(String) called parse(InputSource) + verify(spyReader).parse(any(InputSource.class)); + } + + // --------------------------------------------------------- + // Handler Getter/Setter Tests + // --------------------------------------------------------- + + @Test + public void testContentHandlerAccessors() { + assertNull("Should be null initially", reader.getContentHandler()); + + ContentHandler mockHandler = mock(ContentHandler.class); + reader.setContentHandler(mockHandler); + + assertSame("Should return the set handler", mockHandler, reader.getContentHandler()); + } + + @Test + public void testErrorHandlerAccessors() { + assertNull("Should be null initially", reader.getErrorHandler()); + + ErrorHandler mockHandler = mock(ErrorHandler.class); + reader.setErrorHandler(mockHandler); + + assertSame("Should return the set handler", mockHandler, reader.getErrorHandler()); + } + + @Test + public void testDTDHandlerAccessors() { + assertNull("Should be null initially", reader.getDTDHandler()); + + DTDHandler mockHandler = mock(DTDHandler.class); + reader.setDTDHandler(mockHandler); + + assertSame("Should return the set handler", mockHandler, reader.getDTDHandler()); + } + + @Test + public void testEntityResolverAccessors() { + assertNull("Should be null initially", reader.getEntityResolver()); + + EntityResolver mockResolver = mock(EntityResolver.class); + reader.setEntityResolver(mockResolver); + + assertSame("Should return the set resolver", mockResolver, reader.getEntityResolver()); + } + + // --------------------------------------------------------- + // Helper Method Tests + // --------------------------------------------------------- + + @Test + public void testEnsureHandlerSetSuccess() throws SAXException { + // Setup: Set a handler + reader.setContentHandler(mock(ContentHandler.class)); + + // Execute: Should not throw exception + reader.ensureHandlerSet(); + } + + @Test(expected = SAXException.class) + public void testEnsureHandlerSetFailure() throws SAXException { + // Setup: Ensure handler is null + reader.setContentHandler(null); + + // Execute: Should throw SAXException + reader.ensureHandlerSet(); + } + + // --------------------------------------------------------- + // Feature Flag Tests + // --------------------------------------------------------- + + @Test + public void testGetFeatureNamespaces() throws Exception { + assertTrue("Namespaces should always be true", + reader.getFeature("http://xml.org/sax/features/namespaces")); + } + + @Test + public void testGetFeatureNamespacePrefixes() throws Exception { + assertFalse("Namespace prefixes should always be false", + reader.getFeature("http://xml.org/sax/features/namespace-prefixes")); + } + + @Test(expected = SAXNotRecognizedException.class) + public void testGetFeatureUnknown() throws Exception { + reader.getFeature("http://xml.org/sax/features/unknown-feature"); + } + + @Test + public void testSetFeatureNamespacesTrue() throws Exception { + // Should succeed (no-op) + reader.setFeature("http://xml.org/sax/features/namespaces", true); + } + + @Test(expected = SAXNotSupportedException.class) + public void testSetFeatureNamespacesFalse() throws Exception { + // Should fail - cannot disable namespaces + reader.setFeature("http://xml.org/sax/features/namespaces", false); + } + + @Test + public void testSetFeatureNamespacePrefixesFalse() throws Exception { + // Should succeed (no-op) + reader.setFeature("http://xml.org/sax/features/namespace-prefixes", false); + } + + @Test(expected = SAXNotSupportedException.class) + public void testSetFeatureNamespacePrefixesTrue() throws Exception { + // Should fail - cannot enable namespace prefixes + reader.setFeature("http://xml.org/sax/features/namespace-prefixes", true); + } + + @Test(expected = SAXNotRecognizedException.class) + public void testSetFeatureUnknown() throws Exception { + reader.setFeature("http://xml.org/sax/features/unknown-feature", true); + } + + // --------------------------------------------------------- + // Property Tests + // --------------------------------------------------------- + + @Test(expected = SAXNotRecognizedException.class) + public void testGetPropertyUnknown() throws Exception { + reader.getProperty("http://xml.org/sax/properties/lexical-handler"); + } + + @Test(expected = SAXNotRecognizedException.class) + public void testSetPropertyUnknown() throws Exception { + reader.setProperty("http://xml.org/sax/properties/lexical-handler", new Object()); + } + + // --------------------------------------------------------- + // Concrete Implementation for Testing + // --------------------------------------------------------- + + /** + * A concrete implementation that simulates parsing a simple XML document: + *