Интерфейс SQLXML

public interface SQLXML

Картирование типа SQL XML в языке программирования JavaTM. XML — встроенный тип, который хранит значение XML в качестве значения столбца в строке таблицы базы данных. По умолчанию драйверы реализуют объект SQLXML как логическую ссылку на данные XML, а не на сами данные. Объект SQLXML действителен в течение транзакции, в которой он был создан.

Интерфейс SQLXML предоставляет методы для доступа к значению XML в виде строки, потока чтения или записи или потока. Значение XML также можно получить через источник или установить в результате, которые используются с API-интерфейсами парсеров XML, такими как DOM, SAX и StAX, а также с преобразованиями XSLT и вычислениями XPath.

Методы в интерфейсах ResultSet, CallableStatement и PreparedStatement, такие как getSQLXML, позволяют программисту получить доступ к значению XML. Кроме того, этот интерфейс имеет методы для обновления значения XML.

Значение XML экземпляра SQLXML можно получить как двоичный поток, используя

   SQLXML sqlxml = resultSet.getSQLXML(column);
   InputStream binaryStream = sqlxml.getBinaryStream();
 

Например, для разбора значения XML с помощью парсера DOM:

   DocumentBuilder parser = DocumentBuilderFactory.newInstance().newDocumentBuilder();
   Document result = parser.parse(binaryStream);
 

или для разбора значения XML с помощью парсера SAX вашему обработчику:

   SAXParser parser = SAXParserFactory.newInstance().newSAXParser();
   parser.parse(binaryStream, myHandler);
 

или для разбора значения XML с помощью парсера StAX:

   XMLInputFactory factory = XMLInputFactory.newInstance();
   XMLStreamReader streamReader = factory.createXMLStreamReader(binaryStream);
 

Поскольку базы данных могут использовать оптимизированное представление для XML, доступ к значению через getSource() и setResult() может привести к улучшению производительности обработки без сериализации в представление потока и разбора XML.

Например, для получения узла документа DOM:

   DOMSource domSource = sqlxml.getSource(DOMSource.class);
   Document document = (Document) domSource.getNode();
 

или для установки значения в узел документа DOM в myNode:

   DOMResult domResult = sqlxml.setResult(DOMResult.class);
   domResult.setNode(myNode);
 

или для отправки событий SAX вашему обработчику:

   SAXSource saxSource = sqlxml.getSource(SAXSource.class);
   XMLReader xmlReader = saxSource.getXMLReader();
   xmlReader.setContentHandler(myHandler);
   xmlReader.parse(saxSource.getInputSource());
 

или для установки значения результата из событий SAX:

   SAXResult saxResult = sqlxml.setResult(SAXResult.class);
   ContentHandler contentHandler = saxResult.getHandler();
   contentHandler.startDocument();
   // set the XML elements and attributes into the result
   contentHandler.endDocument();
 

или для получения событий StAX:

   StAXSource staxSource = sqlxml.getSource(StAXSource.class);
   XMLStreamReader streamReader = staxSource.getXMLStreamReader();
 

или для установки значения результата из событий StAX:

   StAXResult staxResult = sqlxml.setResult(StAXResult.class);
   XMLStreamWriter streamWriter = staxResult.getXMLStreamWriter();
 

или для выполнения преобразований XSLT над значением XML, используя XSLT в xsltFile, выводя результат в файл resultFile:

   File xsltFile = new File("a.xslt");
   File myFile = new File("result.xml");
   Transformer xslt = TransformerFactory.newInstance().newTransformer(new StreamSource(xsltFile));
   Source source = sqlxml.getSource(null);
   Result result = new StreamResult(myFile);
   xslt.transform(source, result);
 

или для вычисления выражения XPath над значением XML:

   XPath xpath = XPathFactory.newInstance().newXPath();
   DOMSource domSource = sqlxml.getSource(DOMSource.class);
   Document document = (Document) domSource.getNode();
   String expression = "/foo/@bar";
   String barValue = xpath.evaluate(expression, document);
 

Для установки значения XML, являющегося результатом преобразования XSLT:

   File sourceFile = new File("source.xml");
   Transformer xslt = TransformerFactory.newInstance().newTransformer(new StreamSource(xsltFile));
   Source streamSource = new StreamSource(sourceFile);
   Result result = sqlxml.setResult(null);
   xslt.transform(streamSource, result);
 

Любой источник может быть преобразован в результат с использованием преобразования тождества, заданного вызовом newTransformer():

   Transformer identity = TransformerFactory.newInstance().newTransformer();
   Source source = sqlxml.getSource(null);
   File myFile = new File("result.xml");
   Result result = new StreamResult(myFile);
   identity.transform(source, result);
 

Для записи содержимого источника в стандартный вывод:

   Transformer identity = TransformerFactory.newInstance().newTransformer();
   Source source = sqlxml.getSource(null);
   Result result = new StreamResult(System.out);
   identity.transform(source, result);
 

Для создания DOMSource из DOMResult:

    DOMSource domSource = new DOMSource(domResult.getNode());
 

Неполные или некорректные значения XML могут вызвать SQLException при установке, или исключение может произойти при выполнении execute(). Все потоки должны быть закрыты до выполнения execute(), иначе будет выброшено SQLException.

Чтение и запись значений XML в объект SQLXML или из него могут происходить не более одного раза. Понятийные состояния читаемости и нечитаемости определяют, вернёт ли один из API чтения значение или выбросит исключение. Понятийные состояния писаемости и неписаемости определяют, установит ли один из API записи значение или выбросит исключение.

Состояние меняется с читаемого на нечитаемое после вызова free() или любого из API чтения: getBinaryStream(), getCharacterStream(), getSource(), и getString(). Реализации также могут изменить состояние на неписаемое в этом случае.

Состояние меняется с писаемого на неписаемое после вызова free() или любого из API записи: setBinaryStream(), setCharacterStream(), setResult(), и setString(). Реализации также могут изменить состояние на нечитаемое в этом случае.

Все методы интерфейса SQLXML должны быть полностью реализованы, если драйвер JDBC поддерживает тип данных.