Интерфейс SQLXML

public interface SQLXML extends AutoCloseable

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

Интерфейс SQLXML предоставляет методы для доступа к значению XML в виде String, Reader или Writer либо в виде Stream. Доступ к значению XML также может осуществляться через Source или задаваться как Result. Они используются с API XML-парсеров, такими как DOM, SAX и StAX, а также с преобразованиями XSLT и вычислениями XPath.

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

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

  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 Document:

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

или чтобы присвоить значение узлу DOM Document 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);

Любой Source можно преобразовать в 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);

Чтобы записать содержимое Source в стандартный вывод:

  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 записи значение или выбросит исключение.

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

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

Чтобы освободить ресурсы, используемые объектом SQLXML, приложения должны вызвать метод free() или close(). Любая попытка вызвать метод, отличный от free() или close(), после закрытия объекта SQLXML приведет к выбрасыванию SQLException.

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