Class XmlUtilities

public final class XmlUtilities

JAXB helpers used to read and write engine XML resources.

JAXB contexts are cached by root type. Convenience save methods log marshalling failures and return the requested path; read(Class, URL) exposes unmarshalling failures to its caller.

See Also:

  • Method Details

    • saveWithCustomIndentation

      public static void saveWithCustomIndentation(ByteArrayInputStream input, OutputStream fos, int indentation)

      Writes XML with custom indentation and closes the output stream after a successful transformation.

      If input is the result of JAXB marshalling, set Marshaller.JAXB_FORMATTED_OUTPUT to false so existing indentation does not interfere. Transformation, flushing, and closing failures are logged rather than propagated. The input stream is not closed.

      Parameters:
      input - The input stream that contains the original XML.
      fos - The output stream that is used to save the XML.
      indentation - The indentation with which the XML should be saved.

    • getContext

      public static <T> jakarta.xml.bind.JAXBContext getContext(Class<T> cls)

      Returns the cached JAXB context for a root type, creating it when necessary.

      Context-creation failures are logged.

      Type Parameters:
      T - The root type.
      Parameters:
      cls - The JAXB root type.
      Returns:
      The cached context, or null if it could not be created.

    • read

      public static <T> T read(Class<T> cls, URL path) throws jakarta.xml.bind.JAXBException
      Unmarshals an XML resource and resolves relative URLs against that resource.
      Type Parameters:
      T - The root type.
      Parameters:
      cls - The expected root type.
      path - The resource URL.
      Returns:
      The unmarshalled object, or null if a JAXB context could not be created.
      Throws:
      jakarta.xml.bind.JAXBException - if unmarshalling fails.

    • save

      public static Path save(Object object, Path filePath)

      Marshals an object to a file using formatted XML output.

      Marshalling failures are logged rather than thrown.

      Parameters:
      object - The JAXB object to save.
      filePath - The destination path.
      Returns:
      filePath, or null when the path or JAXB context is unavailable.

    • save

      public static Path save(Object object, Path path, String extension)
      Marshals an object after ensuring that the destination has an extension.
      Parameters:
      object - The JAXB object to save.
      path - The destination path without or with an extension.
      extension - The required extension, with or without a leading dot.
      Returns:
      The actual destination path, or null if saving could not be initialized.