Package ru.bitel.common

# Class XMLUtils

java.lang.Object
ru.bitel.common.XMLUtils

public class XMLUtils extends Object

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `XMLUtils.BGXMLEventReader`
  `static enum`
  `XMLUtils.ErrorShowType`
  что делать с ошибками
  `static class`
  `XMLUtils.XMLEventReaderParameterMap`
  `static class`
  `XMLUtils.XMLStreamReaderParameterMap`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final String`
  `ELEMENT_NAME_ITEM`
  `protected static final String`
  `ELEMENT_NAME_LIST`
  `protected static final String`
  `ELEMENT_NAME_ROW`
  `protected static final Pattern`
  `slashPattern`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `XMLUtils()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Element`
  `addListItem(Node node, int id, String title)`
  `static Element`
  `addListItem(Node node, String id, String title)`
  `static Element`
  `addListItem(Node node, String nameNode, String id, String title)`
  создаёт элемент списка с атрибутами "id"/"title"
  `static ParameterMap`
  `attributesToParameterMap(Element element)`
  `static ParameterMap`
  `attributesToParameterMap(Element element, boolean needEmpty)`
  Обёртывает Element с атрибутами в ParameterMap для тягания этих атрибутов, используется в том числе если надо получить атрибуты сразу удобно как значения разных типов.
  `static final Element`
  `createElement(Document parent, String name)`
  Создать элемент на родительском документе.
  `static Element`
  `createElement(Element parentElement, String name)`
  Создание нового элемента и добавление его в родительский элемент
  `static final Element`
  `createElementNS(Document parent, String xmlns, String name)`
  Создать элемент на родительском документе c заданным xmlns, добавляя его как дочерний.
  `static Element`
  `createListElement(Element parentElement, String name, String itemName, List<?> list, Class<?> clazz, String[] fields)`
  `static Element`
  `createListElement(Element parentElement, String name, List<?> list, Class<?> clazz)`
  Вызов createListElement( parentElement, name, list, clazz, null );
  `static Element`
  `createListElement(Element parentElement, String name, List<?> list, Class<?> clazz, String[] fields)`
  Генерация Элемента содержащего список объектов со значениями свойств в виде аттрибутов
  `static void`
  `createTextNode(Node node, String text)`
  Создание текстового узла - потомка.
  `static Iterable<Element>`
  `elements(NodeList nodeList)`
  Делает Iterable от Element из NodeList, для удобного обхода.
  `static String`
  `escapeXmlNotValid(StringBuilder buf, String value)`
  `static String`
  `getAttribute(Element element, String name)`
  Получение аттрибута элемента.
  `static String`
  `getAttribute(Element element, String name, String defaultValue)`
  Получение аттрибута элемента.
  `static int`
  `getAttributeIntValue(Element element, String name, int defaultValue)`
  Возвращает целочисленное значение атрибута.
  `static Element`
  `getElement(Document doc, String elementName)`
  Ищет элемент в документе по имени.
  `static Node`
  `getNode(Document doc, String nodeName)`
  Берёт Node по имени тега из Document.
  `static Properties`
  `getSerializeProperties(String encoding, boolean indent)`
  `static Properties`
  `getSerializeProperties(String encoding, boolean indent, boolean omitXmlDeclaration)`
  Генерит Properties для использования в трансформере
  `static final Document`
  `newDocument()`
  Создаёт и возвращает новый пустой объект XML документ.
  `static final XMLUtils.BGXMLEventReader`
  `newXMLEventReader(InputStream is)`
  `static final XMLUtils.BGXMLEventReader`
  `newXMLEventReader(Reader reader)`
  `static final XMLUtils.BGXMLEventReader`
  `newXMLEventReader(XMLInputFactory xmlif, InputStream is)`
  `static final XMLUtils.BGXMLEventReader`
  `newXMLEventReader(XMLInputFactory xmlif, Reader reader)`
  `static final XMLInputFactory`
  `newXMLInputFactory()`
  `static Document`
  `parseDocument(byte[] data)`
  `static Document`
  `parseDocument(byte[] data, XMLUtils.ErrorShowType errorShowType)`
  `static Document`
  `parseDocument(String data)`
  `static Document`
  `parseDocument(InputSource source)`
  старый вариант общего метода парсинга документа с showError=true/false, скрывающий экзепшен
  `static void`
  `parseDocument(InputSource source, ContentHandler handler)`
  `static Document`
  `parseDocument(InputSource source, XMLUtils.ErrorShowType errorShowType)`
  общий метод парсинга документа
  `static void`
  `prepareElementToSerialize(Node el)`
  Подготавливает элемент к XML сериализации, заменяет запрещённые символы на \\u{code}.
  `static String`
  `prepareString(StringBuilder buf, String nodeValue)`
  Подготавливает строки к XML сериализации, заменяет запрещённые символы на \\u{code}.
  `static Element`
  `selectElement(Node node, String expression)`
  Возвращает элемент по XPath expression.
  `static Iterable<Element>`
  `selectElements(Node node, String expression)`
  Итератор элементов nodelist по XPath.
  `static Node`
  `selectNode(Node node, String expression)`
  Возвращает Node по XPath expression.
  `static String`
  `selectText(Node node, String expression)`
  Выборка строкового значения по xpath.
  `static String`
  `selectText(Node node, String expression, String defaultValue)`
  Выборка строкового значения по xpath.
  `static void`
  `serialize(Node node, OutputStream os, String encoding)`
  Сериализует в выходной поток с указанием кодировки.
  `static void`
  `serialize(Node node, Result result, String encoding, boolean indent)`
  Сериализует XML документ.
  `static void`
  `serialize(Node node, Result result, Properties properties)`
  `static String`
  `serializeToString(Node node, boolean indent)`
  `static void`
  `setAttribute(Element element, String name, String value)`
  Установка значения атрибута, только если оно не равно null.
  `static void`
  `setPageAttribute(Element element, Page page)`
  заполняет стандартные атрибуты на элементе для объекта Page
  `static void`
  `stringToLines(Element node, String str)`
  `static void`
  `transform(Source xml, Source xslt, Result res, String enc)`
  Трансформация xml+xstl->выход

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### ELEMENT_NAME_ROW

    protected static final String ELEMENT_NAME_ROW
    See Also:
      - Constant Field Values

  - ### ELEMENT_NAME_ITEM

    protected static final String ELEMENT_NAME_ITEM
    See Also:
      - Constant Field Values

  - ### ELEMENT_NAME_LIST

    protected static final String ELEMENT_NAME_LIST
    See Also:
      - Constant Field Values

  - ### slashPattern

    protected static final Pattern slashPattern

- ## Constructor Details

  - ### XMLUtils

    public XMLUtils()

- ## Method Details

  - ### newXMLInputFactory

    public static final XMLInputFactory newXMLInputFactory()

  - ### newXMLEventReader

    public static final XMLUtils.BGXMLEventReader newXMLEventReader(Reader reader) throws ru.bitel.bgbilling.common.BGException
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### newXMLEventReader

    public static final XMLUtils.BGXMLEventReader newXMLEventReader(InputStream is) throws ru.bitel.bgbilling.common.BGException
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### newXMLEventReader

    public static final XMLUtils.BGXMLEventReader newXMLEventReader(XMLInputFactory xmlif, Reader reader) throws ru.bitel.bgbilling.common.BGException
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### newXMLEventReader

    public static final XMLUtils.BGXMLEventReader newXMLEventReader(XMLInputFactory xmlif, InputStream is) throws ru.bitel.bgbilling.common.BGException
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### newDocument

    public static final Document newDocument() throws ru.bitel.bgbilling.common.BGException
    Создаёт и возвращает новый пустой объект XML документ.
    Throws:
      `ru.bitel.bgbilling.common.BGRuntimeException` - при любой ошибке (которой не должно быть по идее)
      `ru.bitel.bgbilling.common.BGException`

  - ### createElement

    public static final Element createElement(Document parent, String name)
    Создать элемент на родительском документе. Ибо для Element версия ни при каких условиях не работает (OwnerDocument всегда null), не помогает и всякие getDocumentElement.
    Parameters:
      `parent` -
      `name` -
    Returns:

  - ### createElement

    public static Element createElement(Element parentElement, String name)
    Создание нового элемента и добавление его в родительский элемент

              element = parentElement.getOwnerDocument().createElement( name );
              parentElement.appendChild( element );

    Parameters:
      `parentElement` - родительский элемент
      `name` - имя нового элемента
    Returns:
      новый элемент

  - ### createElementNS

    public static final Element createElementNS(Document parent, String xmlns, String name)
    Создать элемент на родительском документе c заданным xmlns, добавляя его как дочерний. ...
    Parameters:
      `parent` - документ
      `xmlns` - неймспейс (если null, то будет просто без ns)
      `name` - имя элемента
    Returns:
      созданный элемент.

  - ### createTextNode

    public static void createTextNode(Node node, String text)
    Создание текстового узла - потомка.

             node.appendChild( node.getOwnerDocument().createTextNode( text ) );

    Parameters:
      `node` - узел-предок
      `text` - текст

  - ### createListElement

    public static Element createListElement(Element parentElement, String name, List<?> list, Class<?> clazz) throws ru.bitel.bgbilling.common.BGException
    Вызов createListElement( parentElement, name, list, clazz, null );
    Parameters:
      `parentElement` - родительский элемент
      `name` - имя нового элемента
      `list` - список с объектами для постотроение списка элементов
      `clazz` - класс объектов списка
    Returns:
      корневой элемент списка
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### createListElement

    public static Element createListElement(Element parentElement, String name, List<?> list, Class<?> clazz, String[] fields) throws ru.bitel.bgbilling.common.BGException
    Генерация Элемента содержащего список объектов со значениями свойств в виде аттрибутов
    Parameters:
      `parentElement` - родительский элемент
      `name` - имя нового элемента
      `list` - список с объектами для постотроение списка элементов
      `clazz` - класс объектов списка
      `fields` - список свойств которые нужно добавлять в аттрибуты елементов списка
    Returns:
      корневой элемент списка
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### createListElement

    public static Element createListElement(Element parentElement, String name, String itemName, List<?> list, Class<?> clazz, String[] fields) throws ru.bitel.bgbilling.common.BGException
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### addListItem

    public static Element addListItem(Node node, int id, String title)

  - ### addListItem

    public static Element addListItem(Node node, String id, String title)

  - ### addListItem

    public static Element addListItem(Node node, String nameNode, String id, String title)
    создаёт элемент списка с атрибутами "id"/"title"

  - ### setPageAttribute

    public static void setPageAttribute(Element element, Page page)
    заполняет стандартные атрибуты на элементе для объекта Page

  - ### setAttribute

    public static void setAttribute(Element element, String name, String value)
    Установка значения атрибута, только если оно не равно null.
    Parameters:
      `element` - элемент
      `name` - имя аттрибута
      `value` - значение аттрибута

  - ### parseDocument

    public static Document parseDocument(String data)

  - ### parseDocument

    public static Document parseDocument(byte[] data)

  - ### parseDocument

    public static Document parseDocument(byte[] data, XMLUtils.ErrorShowType errorShowType)

  - ### parseDocument

    public static Document parseDocument(InputSource source)
    старый вариант общего метода парсинга документа с showError=true/false, скрывающий экзепшен

  - ### parseDocument

    public static Document parseDocument(InputSource source, XMLUtils.ErrorShowType errorShowType)
    общий метод парсинга документа
    Throws:
      `ru.bitel.bgbilling.common.BGException` - если вариант кинуть ошибку (оригинальный экзепшен будет в cause)

  - ### parseDocument

    public static void parseDocument(InputSource source, ContentHandler handler) throws ru.bitel.bgbilling.common.BGException
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### getElement

    public static Element getElement(Document doc, String elementName)
    Ищет элемент в документе по имени. Если не находит - возвращает созданный.
    Parameters:
      `doc` -
      `elementName` -
    Returns:

  - ### getNode

    public static Node getNode(Document doc, String nodeName)
    Берёт Node по имени тега из Document. В случае отсутствия - создаёт новый Node и возвращает его.
    Parameters:
      `doc` - документ
      `nodeName` - имя узла
    Returns:
      узел
    See Also:
      - invalid reference

            findElement

  - ### selectElement

    public static Element selectElement(Node node, String expression) throws ru.bitel.bgbilling.common.BGException
    Возвращает элемент по XPath expression.
    Parameters:
      `node` -
      `expression` - XPath expression
    Returns:
      элемент, если найден - иначе null
    Throws:
      `ru.bitel.bgbilling.common.BGException`
    See Also:
      - `selectNode(Node, String)`

  - ### selectNode

    public static Node selectNode(Node node, String expression) throws ru.bitel.bgbilling.common.BGException
    Возвращает Node по XPath expression. Пример: /data/table - выбрать элемент table лежащий в корне. Пример: //table - выбрать элемент table где попало
    Parameters:
      `node` -
      `expression` - XPath expression
    Returns:
      Node, если найден - иначе null
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### selectElements

    public static Iterable<Element> selectElements(Node node, String expression)
    Итератор элементов nodelist по XPath. Пример: /tables/* - выбрать все элементы внутри родительского tables в корне.

  - ### elements

    public static Iterable<Element> elements(NodeList nodeList)
    Делает Iterable от Element из NodeList, для удобного обхода.
    Parameters:
      `nodeList` - исходный NodeList
    Returns:
      Iterable<Element>.

  - ### selectText

    public static String selectText(Node node, String expression) throws ru.bitel.bgbilling.common.BGException
    Выборка строкового значения по xpath. Дефолт валуе - null.
    Throws:
      `ru.bitel.bgbilling.common.BGException`
    See Also:
      - `selectText(Node, String, String)`

  - ### selectText

    public static String selectText(Node node, String expression, String defaultValue) throws ru.bitel.bgbilling.common.BGException
    Выборка строкового значения по xpath. То есть практически тоже самое, что selectNode, только от него возвращается node value, либо null, если что-то не найдено или какая-то ошибка (нуть не должен возвращать текст итд) Может возвращать и значения текстовых нод и значения атрибутов, универсальная.
    В целом, не предназначен для выборок вроде selectText( node, "@selected", null), потому что в том что getAttribute возвращает не null, а пустую строку нет ничего страшного. Тем более есть метод, который и null возвращает и работает быстрее.
    Примеры запросов:
    1) запрос текстового значения атрибута

         <data><payment cardnumber="111">...
         /data/payment/@cardnumber

    2) запрос текстового значения ноды

         ...<operation><pursesrc>текст</pursesrc>...
         /operation/pursesrc/text()

    3) не от корня, а относительно - начиная не со сшеша
    4) искать где попало - два слеша
    5) и т.д., ну вы поняли
    Parameters:
      `node` - ноде корневой
      `expression` - xpath
      `defaultValue` - значение по умолчанию
    Returns:
      строка
    Throws:
      `ru.bitel.bgbilling.common.BGException`
    See Also:
      - `selectNode(org.w3c.dom.Node, java.lang.String)`

  - ### getAttribute

    public static String getAttribute(Element element, String name)
    Получение аттрибута элемента. Когда нет аттрибута - возвращает null.
    Parameters:
      `element` - элемент
      `name` - имя аттрибута
    Returns:
      строка значение аттрибута (или нулл)

  - ### getAttribute

    public static String getAttribute(Element element, String name, String defaultValue)
    Получение аттрибута элемента. Сделана ввиду дурацкой domовской привычки доставать несуществующие принципиально аттрибуты как пустые строки, что не может меня не волновать при реализации некоторых задумок, пусть когда нет аттрибута - возвращает defaultValue.
    Parameters:
      `element` - элемент
      `name` - имя аттрибута
      `defaultValue` - значение по умолчанию.
    Returns:
      строка значение аттрибута (или значение по умолчанию)

  - ### getAttributeIntValue

    public static int getAttributeIntValue(Element element, String name, int defaultValue)
    Возвращает целочисленное значение атрибута.
    Parameters:
      `element` -
      `name` -
      `defaultValue` -
    Returns:

  - ### attributesToParameterMap

    public static ParameterMap attributesToParameterMap(Element element, boolean needEmpty)
    Обёртывает Element с атрибутами в ParameterMap для тягания этих атрибутов, используется в том числе если надо получить атрибуты сразу удобно как значения разных типов.

  - ### attributesToParameterMap

    public static ParameterMap attributesToParameterMap(Element element)

  - ### serialize

    public static void serialize(Node node, OutputStream os, String encoding) throws ru.bitel.bgbilling.common.BGException
    Сериализует в выходной поток с указанием кодировки. Без отступов.
    Parameters:
      `node` - нода (обычно Document)
      `os` - OutputStream
      `encoding` - кодировка (и документа и представления в байтовой строке)
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### serialize

    public static void serialize(Node node, Result result, String encoding, boolean indent) throws ru.bitel.bgbilling.common.BGException
    Сериализует XML документ.
    Parameters:
      `node` - - узел документа.
      `result` - - объект с результатом (если надо во Writer, то обернуть в StreamResult).
      `encoding` - - кодировка, может быть null.
      `indent` - - форматирование (отступы).
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### serializeToString

    public static String serializeToString(Node node, boolean indent) throws ru.bitel.bgbilling.common.BGException
    Parameters:
      `node` - нода (обычно xml-документ)
      `indent` - есть отступы или нет
    Returns:
      содержимое xml документа в виде строки, в uft-8, с отступами (при indent=true) и с начальным xml-declaration
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### getSerializeProperties

    public static Properties getSerializeProperties(String encoding, boolean indent)

  - ### getSerializeProperties

    public static Properties getSerializeProperties(String encoding, boolean indent, boolean omitXmlDeclaration)
    Генерит Properties для использования в трансформере
    Parameters:
      `encoding` - кодировка
      `indent` - отступы в форматировании
      `omitXmlDeclaration` - подавлять ?xml заголовок

  - ### serialize

    public static void serialize(Node node, Result result, Properties properties) throws ru.bitel.bgbilling.common.BGException
    Throws:
      `ru.bitel.bgbilling.common.BGException`

  - ### prepareElementToSerialize

    public static void prepareElementToSerialize(Node el)
    Подготавливает элемент к XML сериализации, заменяет запрещённые символы на \\u{code}. Используется в местах, где возможно появление недопустимых XML символов.
    Parameters:
      `el` - исходный элемент в теле, названии, дочерних элементах и атрибутах возможны запрещённые символы.

  - ### prepareString

    public static String prepareString(StringBuilder buf, String nodeValue)
    Подготавливает строки к XML сериализации, заменяет запрещённые символы на \\u{code}. Используется в местах, где возможно появление недопустимых XML символов.
    Parameters:
      `buf` - вспомогательный буфер, в который складывается результат, чтобы не выделять каждый раз заново.
      `nodeValue` - исходная строка, где возможны запрещённые символы.
    Returns:

  - ### transform

    public static void transform(Source xml, Source xslt, Result res, String enc) throws TransformerException
    Трансформация xml+xstl->выход
    Parameters:
      `xml` - исходный документ xml в виде Source.
      `xslt` - исходный документ xslt в виде Source.
      `res` - результат (например, готовый FO-документ) в виде Result.
      `enc` - кодировка.
    Throws:
      `TransformerException` - ошибка трансформации.

  - ### escapeXmlNotValid

    public static String escapeXmlNotValid(StringBuilder buf, String value)

  - ### stringToLines

    public static void stringToLines(Element node, String str)