Интерфейс SQLXML

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

Интерфейс SQLXML предоставляет методы для доступа к значению XML в виде строки, объекта Reader или Writer или потока. Значение 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();

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

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

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();

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

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

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

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

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

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 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);

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);

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 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-драйвер поддерживает тип данных.

Методы

free

void free()
   throws SQLException

Этот метод закрывает этот объект и освобождает ресурсы, которые он удерживал. Объект SQL XML становится недоступным для чтения и записи после вызова этого метода. После того, как free был вызван, любая попытка вызвать метод, отличный от free, приведет к выбрасыванию SQLException. Если free вызывается несколько раз, последующие вызовы free обрабатываются как нетранзакционные.

Исключение:

SQLException - если произошла ошибка при освобождении значения XML.

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.6

getBinaryStream

InputStream getBinaryStream()
                     throws SQLException

Возвращает:

поток, содержащий данные XML.

Исключение:

SQLException - если произошла ошибка при обработке значения XML. Исключение выбрасывается, если состояние не является читаемым.

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.6

setBinaryStream

OutputStream setBinaryStream()
                      throws SQLException

Возвращает:

поток, в который можно записывать данные.

Исключение:

SQLException - если произошла ошибка при обработке значения XML. Исключение выбрасывается, если состояние не является записываемым.

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.6

getCharacterStream

Reader getCharacterStream()
                   throws SQLException

Возвращает:

поток, содержащий данные XML.

Исключение:

SQLException - если произошла ошибка при обработке значения XML. Метод getCause() исключения может предоставить более подробное исключение, например, если поток не содержит допустимых символов. Исключение выбрасывается, если состояние не является читаемым.

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.6

setCharacterStream

Writer setCharacterStream()
                   throws SQLException

Возвращает:

поток, в который можно записывать данные.

Исключение:

SQLException - если произошла ошибка при обработке значения XML. Метод getCause() исключения может предоставить более подробное исключение, например, если поток не содержит допустимых символов. Исключение выбрасывается, если состояние не является записываемым.

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.6

getString

String getString()
          throws SQLException

Возвращает:

строковое представление значения XML, обозначенного этим экземпляром SQLXML.

Исключение:

SQLException - если произошла ошибка при обработке значения XML. Метод getCause() исключения может предоставить более подробное исключение, например, если поток не содержит допустимых символов. Исключение выбрасывается, если состояние не является читаемым.

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.6

setString

void setString(String value)
        throws SQLException

Параметры:

value - значение XML

Исключение:

SQLException - если произошла ошибка при обработке значения XML. Метод getCause() исключения может предоставить более подробное исключение, например, если поток не содержит допустимых символов. Исключение выбрасывается, если состояние не является записываемым.

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.6

getSource

<T extends Source> T getSource(Class<T> sourceClass)
                        throws SQLException

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

Параметры типа:

T - тип класса, моделируемого этим объектом Class

Параметры:

sourceClass - Класс источника или null. Если класс равен null, будет возвращена реализация источника, специфичная для поставщика. Следующие классы поддерживаются как минимум:

javax.xml.transform.dom.DOMSource - returns a DOMSource
   javax.xml.transform.sax.SAXSource - returns a SAXSource
   javax.xml.transform.stax.StAXSource - returns a StAXSource
   javax.xml.transform.stream.StreamSource - returns a StreamSource

Возвращает:

Source для чтения значения XML.

Исключение:

SQLException - если произошла ошибка при обработке значения XML или эта функция не поддерживается. Метод getCause() исключения может предоставить более подробное исключение, например, если произошла ошибка парсера XML. Исключение выбрасывается, если состояние не является читаемым.

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.6

setResult

<T extends Result> T setResult(Class<T> resultClass)
                        throws SQLException

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

Параметры типа:

T - тип класса, моделируемого этим объектом Class

Параметры:

resultClass - Класс результата или null. Если resultClass равен null, будет возвращена реализация Result, специфичная для поставщика. Следующие классы поддерживаются как минимум:

javax.xml.transform.dom.DOMResult - returns a DOMResult
   javax.xml.transform.sax.SAXResult - returns a SAXResult
   javax.xml.transform.stax.StAXResult - returns a StAXResult
   javax.xml.transform.stream.StreamResult - returns a StreamResult

Возвращает:

Возвращает Result для установки значения XML.

Исключение:

SQLException - если произошла ошибка при обработке значения XML или эта функция не поддерживается. Метод getCause() исключения может предоставить более подробное исключение, например, если произошла ошибка парсера XML. Исключение выбрасывается, если состояние не является записываемым.

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.6