Fix AXIS2-6053: Add diagnostic hints for unresolved attribute ref= in schema validation

When a schema uses xs:attribute ref= to reference an attribute from an
external namespace (e.g., xmime:contentType) and the referenced schema
cannot be resolved, the validator produces a cryptic cvc-complex-type.3.2.2
error. This change detects that error code and appends an actionable hint
explaining the likely cause and remediation.

Also improves SchemaFactoryErrorHandler to log warnings with full exception
context, making unresolvable import warnings visible for diagnosis.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: robertlazarski

modules/schema-validation/pom.xml

@@ -49,6 +49,16 @@
             <artifactId>axis2-kernel</artifactId>
             <version>${project.version}</version>
         </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

modules/schema-validation/src/main/java/org/apache/axis2/validation/SchemaFactoryErrorHandler.java

@@ -29,7 +29,7 @@ final class SchemaFactoryErrorHandler implements ErrorHandler {
 
     @Override
     public void warning(SAXParseException exception) throws SAXException {
-        log.warn(exception.getMessage());
+        log.warn("Schema compilation warning: " + exception.getMessage(), exception);
     }
 
     @Override

modules/schema-validation/src/main/java/org/apache/axis2/validation/SchemaValidationHandler.java

@@ -71,15 +71,29 @@ public InvocationResponse invoke(MessageContext msgContext) throws AxisFault {
         try {
             schema = schemaFactory.newSchema(schemaSources.toArray(new Source[schemaSources.size()]));
         } catch (SAXException ex) {
-            throw new AxisFault("Failed to compile schemas", ex);
+            throw new AxisFault("Failed to compile schemas: " + ex.getMessage()
+                    + appendRefHint(ex), ex);
         }
         try {
             schema.newValidator().validate(msgContext.getEnvelope().getBody().getFirstElement().getSAXSource(true));
         } catch (SAXException ex) {
-            throw new AxisFault("Failed to validate message: " + ex.getMessage(), ex);
+            throw new AxisFault("Failed to validate message: " + ex.getMessage()
+                    + appendRefHint(ex), ex);
         } catch (OMException | IOException ex) {
             throw new AxisFault("Failed to validate message", ex);
         }
         return InvocationResponse.CONTINUE;
     }
+
+    static String appendRefHint(SAXException ex) {
+        String msg = ex.getMessage();
+        if (msg != null && msg.contains("cvc-complex-type.3.2.2")) {
+            return ". This may be caused by a schema using xs:attribute ref= to reference"
+                    + " an attribute from an external namespace (e.g., xmime:contentType)"
+                    + " whose schema was not imported or could not be resolved."
+                    + " Consider defining the attribute inline instead of using ref=,"
+                    + " or ensure the referenced schema is accessible.";
+        }
+        return "";
+    }
 }

modules/schema-validation/src/test/java/org/apache/axis2/validation/SchemaValidationHandlerTest.java

@@ -0,0 +1,51 @@
+/*
+ * 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
+ *
+ * http://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.
+ */
+package org.apache.axis2.validation;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import org.junit.jupiter.api.Test;
+import org.xml.sax.SAXException;
+
+public class SchemaValidationHandlerTest {
+
+    @Test
+    public void testAppendRefHintForCvcComplexType322() {
+        SAXException ex = new SAXException(
+                "cvc-complex-type.3.2.2: Attribute 'contentType' is not allowed to appear in element 'foo'");
+        String hint = SchemaValidationHandler.appendRefHint(ex);
+        assertThat(hint).contains("xs:attribute ref=");
+        assertThat(hint).contains("xmime:contentType");
+        assertThat(hint).contains("not imported or could not be resolved");
+    }
+
+    @Test
+    public void testAppendRefHintReturnsEmptyForOtherErrors() {
+        SAXException ex = new SAXException("cvc-type.3.1.3: some other validation error");
+        String hint = SchemaValidationHandler.appendRefHint(ex);
+        assertThat(hint).isEmpty();
+    }
+
+    @Test
+    public void testAppendRefHintHandlesNullMessage() {
+        SAXException ex = new SAXException((String) null);
+        String hint = SchemaValidationHandler.appendRefHint(ex);
+        assertThat(hint).isEmpty();
+    }
+}