README - master - miktim/java-xmlgen

README
123 строки4 KB
miktim
1.3.2
10 авг 2026, 06:35
10 авг 2026, 06:35c6ac202
XMLgen - The simplest XML generator, MIT (c) 2026 miktim@mail.ru

There are enough advanced XML generators. 
This is an attempt to implement the simplest one.

The jar ./dist/xmlgen-... file was generated with debugging info
using JDK1.8 for target JRE1.7

package org.miktim.xmlgen;

class XML extends Node;
  Constructor:
    XML();
      - creates an empty XML.
    XML(Node rootNode);
      - creates an XML with the root node;
      - avoid recursion!

  Constant:
    statc String NAME_PATTERN;
      - the regex XML names pattern: xml_name[:xml_name]
  Methods:
    String toString();
      - returns XML text encoded in the JVM's DEFAULT charset.
    String toString(String charset) throws UnsupportedEncodingException;
      - returns XML text encoded in the specified charset
    void toStream(OutputStream out) throws IOException;
      - writes XML text, encoded in the JVM's DEFAULT charset,
        to the output stream and closes this stream.
    void toStream(OutputStream out, String charset) throws IOException;
      - writes XML text, encoded in the specified charset,
        to the output stream and closes this stream.

  Note:
    In Java 17 and earlier, the default charset was dynamic;
    it was determined at startup based on the user's operating system,
    locale, and regional settings (e.g., windows-1252 on Western Windows).

class Node;
  Node is XML element node.

  Constructors:
    Node();
      - creates a "null" node. It's a ghost.
    Node(String tag);
      - creates a node;
      - the tag is a node name with an optional prefix and optional attributes;
      - the tag syntax is checked.
        Example:
          new Node("prop xmlns:R=\"http://ns.example.com/schema/\"");
    Node(String tag, Object content);
      - creates a node with content;
      - escapes the text (String instance) content;
      - the content can be null.
        Examples:
          new Node("R:author", "John Doe");
          new Node("IsReadOnly xmlns=\"http://ucb.openoffice.org/dav/props/\"",false);

    Throws:
      NullPointerException: when the tag is null;
      IllegalArgumentException: when the tag is empty or syntactically incorrect.

  Methods:
    Node setNode(Node node);
      - adds the node to the parent Node;
      - avoid recursion!;
      - sets the node as the parent.
    Node addNode(Node node);
      - adds the node to the parent Node.
      - avoid recursion!
    Node setNode(String tag);
      - adds new node to the parent Node;
      - sets new node as the parent.
    Node addNode(String tag);
      - adds new node to the parent Node;
    Node setNode(String tag, Object content);
      - adds new node to the parent Node;
      - sets new node as the parent.
    Node addNode(String tag, Object content);
      - adds new node to the parent Node;

    Throws:
      NullPointerException: when argument Node is null;
      NoSuchElementException: when trying addNode to an empty XML or empty "null" node. 

    boolean isEmpty();
      - checks if the node (xml) is empty.
    static String escape(String value);
      - escapes "<", ">", "&".
    String toString();
      - returns XML text as a single line.

Example:

  XML xml = new XML();
  xml.setNode("multistatus xmlns=\"DAV:\"")
       .setNode("response")
         .addNode("href", "http://www.example.com/container/")
         .setNode("propstat")
           .addNode("status", "HTTP/1.1 200 OK")
           .setNode("prop xmlns:R=\"http://ns.example.com/schema/\"")
             .addNode("R:author", "John Doe")
             .addNode("creationdate", "2026-06-12T23:20:50.52Z")
             .addNode("displayname", "container")
             .addNode("supportedlock");

xml.toString() returns following XML text (actually as single line):

<?xml version="1.0" encoding="utf-8" ?>
<multistatus xmlns="DAV:">
  <response>
    <href>http://www.example.com/container/</href>
    <propstat>
      <status>HTTP/1.1 200 OK</status>
      <prop xmlns:R="http://ns.example.com/schema/">
        <R:author>John Doe</R:author>
        <creationdate>2026-06-12T23:20:50.52Z</creationdate>
        <displayname>container</displayname>
        <supportedlock/>
      </prop>
    </propstat>
  </response>
</multistatus>