Both Log4j 1.x and Log4j 2.x support use of XML files to specify logging configuration. This post looks into some of the nuances and subtleties associated with using JAXB to work with these XML configuration files via Java classes. The examples in this post are based on Apache Log4j 1.2.17, Apache Log4j 2.6.2, and Java 1.8.0_73 with JAXB xjc 2.2.8-b130911.1802.
Log4j 1.x : log4j.dtd
Log4j 1.x's XML grammar is defined by a DTD instead of an W3C XML Schema. Fortunately, the JAXB implementation that comes with the JDK provides an "experimental,unsupported" option for using DTDs as the input from which Java classes are generated. The following command can be used to run the xjc command-line tool against the log4j.dtd.
xjc -p dustin.examples.l4j1 -d src -dtd log4j.dtd
The next screen snapshot demonstrates this.
Running the command described above and demonstrated in the screen snapshot leads to Java classes being generated in a Java package in the src directory called dustin.examples.l4fj1 that allow for unmarshalling from log4j.dtd-compliant XML and for marshalling to log4j.dtd-compliant XML.
Log4j 2.x : Log4j-config.xsd
Log4j 2.x's XML configuration can be either "concise" or "strict" and I need to use "strict" in this post because that is the form that uses a grammar defined by the W3C XML Schema file Log4j-config.xsd and I need a schema to generate Java classes with JAXB. The following command can be run against this XML Schema to generate Java classes representing Log4j2 strict XML.
xjc -p dustin.examples.l4j2 -d src Log4j-config.xsd -b l4j2.jxb
Running the above command leads to Java classes being generated in a Java package in the src directory called dustin.examples.l4j2 that allow for unmarshalling from Log4j-config.xsd-compliant XML and for marshalling to Log4j-config.xsd-compliant XML.
In the previous example, I included a JAXB binding file with the option -b followed by the name of the binding file (-b l4j2.jxb). This binding was needed to avoid an error that prevented xjc from generated Log4j 2.x-compliant Java classes with the error message, "Property "Value" is already defined. Use <jaxb:property> to resolve this conflict." This issue and how to resolve it are discussed in A Brit in Bermuda's post Property "Value" is already defined. Use to resolve this conflict. The source for the JAXB binding file I used here is shown next.
l4j2.jxb
<jxb:bindings version="2.0"
xmlns:jxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<jxb:bindings schemaLocation="Log4j-config.xsd" node="/xsd:schema">
<jxb:bindings node="//xsd:complexType[@name='KeyValuePairType']">
<jxb:bindings node=".//xsd:attribute[@name='value']">
<jxb:property name="pairValue"/>
</jxb:bindings>
</jxb:bindings>
</jxb:bindings>
</jxb:bindings>
The JAXB binding file just shown allows xjc to successfully parse the XSD and generate the Java classes. The one small price to pay (besides writing and referencing the binding file) is that the "value" attribute of the KeyValuePairType will need to be accessed in the Java class as a field named pairValue instead of value.
Unmarshalling Log4j 1.x XML
A potential use case for working with JAXB-generated classes for Log4j 1.x's log4j.dtd and Log4j 2.x's Log-config.xsd is conversion of Log4j 1.x XML configuration files to Log4j 2.x "strict" XML configuration files. In this situation, one would need to unmarshall Log4j 1.x log4j.dtd-compliant XML and marshall Log4j 2.x Log4j-config.xsd-compliant XML.
The following code listing demonstrates how the Log4j 1.x XML might be unmarshalled using the previously generated JAXB classes.
/**
* Extract the contents of the Log4j 1.x XML configuration file
* with the provided path/name.
*
* @param log4j1XmlFileName Path/name of Log4j 1.x XML config file.
* @return Contents of Log4j 1.x configuration file.
* @throws RuntimeException Thrown if exception occurs that prevents
* extracting contents from XML with provided name.
*/
public Log4JConfiguration readLog4j1Config(final String log4j1XmlFileName)
throws RuntimeException
{
Log4JConfiguration config;
try
{
final File inputFile = new File(log4j1XmlFileName);
if (!inputFile.isFile())
{
throw new RuntimeException(log4j1XmlFileName + " is NOT a parseable file.");
}
final SAXParserFactory spf = SAXParserFactory.newInstance();
final SAXParser sp = spf.newSAXParser();
final XMLReader xr = sp.getXMLReader();
final JAXBContext jaxbContext = JAXBContext.newInstance("dustin.examples.l4j1");
final Unmarshaller unmarshaller = jaxbContext.createUnmarshaller();
final UnmarshallerHandler unmarshallerHandler = unmarshaller.getUnmarshallerHandler();
xr.setContentHandler(unmarshallerHandler);
final FileInputStream xmlStream = new FileInputStream(log4j1XmlFileName);
final InputSource xmlSource = new InputSource(xmlStream);
xr.parse(xmlSource);
final Object unmarshalledObject = unmarshallerHandler.getResult();
config = (Log4JConfiguration) unmarshalledObject;
}
catch (JAXBException | ParserConfigurationException | SAXException | IOException exception)
{
throw new RuntimeException(
"Unable to read from file " + log4j1XmlFileName + " - " + exception,
exception);
}
return config;
}
Unmarshalling this Log4j 1.x XML was a bit trickier than some XML unmarshalling because of the nature of log4j.dtd's namespace treatment. This approach for dealing with this wrinkle is described in Gik's Jaxb UnMarshall without namespace and in Deepa S's How to instruct JAXB to ignore Namespaces. Using this approach helped avoid the error message:
UnmarshalException: unexpected element (uri:"http://jakarta.apache.org/log4j/", local:"configuration"). Expected elements ...
To unmarshall the Log4j 1.x that in my case references log4j.dtd on the filesystem, I needed to provide a special Java system property to the Java launcher when running this code with Java 8. Specifically, I needed to specify
-Djavax.xml.accessExternalDTD=all
to avoid the error message, "Failed to read external DTD because 'file' access is not allowed due to restriction set by the accessExternalDTD property." Additional details on this can be found at NetBeans's FaqWSDLExternalSchema Wiki page.
Marshalling Log4j 2.x XML
Marshalling Log4j 2.x XML using the JAXB-generated Java classes is fairly straightforward as demonstrated in the following example code:
/**
* Write Log4j 2.x "strict" XML configuration to file with
* provided name based on provided content.
*
* @param log4j2Configuration Content to be written to Log4j 2.x
* XML configuration file.
* @param log4j2XmlFile File to which Log4j 2.x "strict" XML
* configuration should be written.
*/
public void writeStrictLog4j2Config(
final ConfigurationType log4j2Configuration,
final String log4j2XmlFile)
{
try (final OutputStream os = new FileOutputStream(log4j2XmlFile))
{
final JAXBContext jc = JAXBContext.newInstance("dustin.examples.l4j2");
final Marshaller marshaller = jc.createMarshaller();
marshaller.setProperty(Marshaller.JAXB_FORMATTED_OUTPUT, true);
marshaller.marshal(new ObjectFactory().createConfiguration(log4j2Configuration), os);
}
catch (JAXBException | IOException exception)
{
throw new RuntimeException(
"Unable to write Log4 2.x XML configuration - " + exception,
exception);
}
}
There is one subtlety in this marshalling case that may not be obvious in the just-shown code listing. The classes that JAXB's xjc generated from the Log4j-config.xsd lack any class with @XmlRootElement. The JAXB classes that were generated from the Log4j 1.x log4j.dtd did include classes with this @XmlRootElement annotation. Because the Log4j 2.x Log4j-config.xsd-based Java classes don't have this annotation, the following error occurs when trying to marshal the ConfigurationType instance directly:
MarshalException - with linked exception: [com.sun.istack.internal.SAXException2: unable to marshal type "dustin.examples.l4j2.ConfigurationType" as an element because it is missing an @XmlRootElement annotation]
To avoid this error, I instead (line 18 of above code listing) marshalled the result of invoking new ObjectFactory().createConfiguration(ConfigurationType) on the passed-in ConfigurationType instance and it is now successfully marshalled.
Conclusion
JAXB can be used to generate Java classes from Log4j 1.x's log4j.dtd and from Log4j 2.x's Log4j-config.xsd, but there are some subtleties and nuances associated with this process to successfully generate these Java classes and to use the generated Java classes to marshal and unmarshal XML.
No comments:
Post a Comment