1 /*
2 * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
343 * Returns a Source for reading the XML value designated by this SQLXML instance.
344 * Sources are used as inputs to XML parsers and XSLT transformers.
345 * <p>
346 * Sources for XML parsers will have namespace processing on by default.
347 * The systemID of the Source is implementation dependent.
348 * <p>
349 * The SQL XML object becomes not readable when this method is called and
350 * may also become not writable depending on implementation.
351 * <p>
352 * Note that SAX is a callback architecture, so a returned
353 * SAXSource should then be set with a content handler that will
354 * receive the SAX events from parsing. The content handler
355 * will receive callbacks based on the contents of the XML.
356 * <pre>
357 * SAXSource saxSource = sqlxml.getSource(SAXSource.class);
358 * XMLReader xmlReader = saxSource.getXMLReader();
359 * xmlReader.setContentHandler(myHandler);
360 * xmlReader.parse(saxSource.getInputSource());
361 * </pre>
362 *
363 * @param sourceClass The class of the source, or null.
364 * If the class is null, a vendor specifc Source implementation will be returned.
365 * The following classes are supported at a minimum:
366 * <pre>
367 * javax.xml.transform.dom.DOMSource - returns a DOMSource
368 * javax.xml.transform.sax.SAXSource - returns a SAXSource
369 * javax.xml.transform.stax.StAXSource - returns a StAXSource
370 * javax.xml.transform.stream.StreamSource - returns a StreamSource
371 * </pre>
372 * @return a Source for reading the XML value.
373 * @throws SQLException if there is an error processing the XML value
374 * or if this feature is not supported.
375 * The getCause() method of the exception may provide a more detailed exception, for example,
376 * if an XML parser exception occurs.
377 * An exception is thrown if the state is not readable.
378 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
379 * this method
380 * @since 1.6
381 */
382 <T extends Source> T getSource(Class<T> sourceClass) throws SQLException;
384 /**
385 * Returns a Result for setting the XML value designated by this SQLXML instance.
386 * <p>
387 * The systemID of the Result is implementation dependent.
388 * <p>
389 * The SQL XML object becomes not writeable when this method is called and
390 * may also become not readable depending on implementation.
391 * <p>
392 * Note that SAX is a callback architecture and the returned
393 * SAXResult has a content handler assigned that will receive the
394 * SAX events based on the contents of the XML. Call the content
395 * handler with the contents of the XML document to assign the values.
396 * <pre>
397 * SAXResult saxResult = sqlxml.setResult(SAXResult.class);
398 * ContentHandler contentHandler = saxResult.getXMLReader().getContentHandler();
399 * contentHandler.startDocument();
400 * // set the XML elements and attributes into the result
401 * contentHandler.endDocument();
402 * </pre>
403 *
404 * @param resultClass The class of the result, or null.
405 * If resultClass is null, a vendor specific Result implementation will be returned.
406 * The following classes are supported at a minimum:
407 * <pre>
408 * javax.xml.transform.dom.DOMResult - returns a DOMResult
409 * javax.xml.transform.sax.SAXResult - returns a SAXResult
410 * javax.xml.transform.stax.StAXResult - returns a StAXResult
411 * javax.xml.transform.stream.StreamResult - returns a StreamResult
412 * </pre>
413 * @return Returns a Result for setting the XML value.
414 * @throws SQLException if there is an error processing the XML value
415 * or if this feature is not supported.
416 * The getCause() method of the exception may provide a more detailed exception, for example,
417 * if an XML parser exception occurs.
418 * An exception is thrown if the state is not writable.
419 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
420 * this method
421 * @since 1.6
422 */
423 <T extends Result> T setResult(Class<T> resultClass) throws SQLException;
|
1 /*
2 * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
343 * Returns a Source for reading the XML value designated by this SQLXML instance.
344 * Sources are used as inputs to XML parsers and XSLT transformers.
345 * <p>
346 * Sources for XML parsers will have namespace processing on by default.
347 * The systemID of the Source is implementation dependent.
348 * <p>
349 * The SQL XML object becomes not readable when this method is called and
350 * may also become not writable depending on implementation.
351 * <p>
352 * Note that SAX is a callback architecture, so a returned
353 * SAXSource should then be set with a content handler that will
354 * receive the SAX events from parsing. The content handler
355 * will receive callbacks based on the contents of the XML.
356 * <pre>
357 * SAXSource saxSource = sqlxml.getSource(SAXSource.class);
358 * XMLReader xmlReader = saxSource.getXMLReader();
359 * xmlReader.setContentHandler(myHandler);
360 * xmlReader.parse(saxSource.getInputSource());
361 * </pre>
362 *
363 * @param <T> the type of the class modeled by this Class object
364 * @param sourceClass The class of the source, or null.
365 * If the class is null, a vendor specifc Source implementation will be returned.
366 * The following classes are supported at a minimum:
367 * <pre>
368 * javax.xml.transform.dom.DOMSource - returns a DOMSource
369 * javax.xml.transform.sax.SAXSource - returns a SAXSource
370 * javax.xml.transform.stax.StAXSource - returns a StAXSource
371 * javax.xml.transform.stream.StreamSource - returns a StreamSource
372 * </pre>
373 * @return a Source for reading the XML value.
374 * @throws SQLException if there is an error processing the XML value
375 * or if this feature is not supported.
376 * The getCause() method of the exception may provide a more detailed exception, for example,
377 * if an XML parser exception occurs.
378 * An exception is thrown if the state is not readable.
379 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
380 * this method
381 * @since 1.6
382 */
383 <T extends Source> T getSource(Class<T> sourceClass) throws SQLException;
385 /**
386 * Returns a Result for setting the XML value designated by this SQLXML instance.
387 * <p>
388 * The systemID of the Result is implementation dependent.
389 * <p>
390 * The SQL XML object becomes not writeable when this method is called and
391 * may also become not readable depending on implementation.
392 * <p>
393 * Note that SAX is a callback architecture and the returned
394 * SAXResult has a content handler assigned that will receive the
395 * SAX events based on the contents of the XML. Call the content
396 * handler with the contents of the XML document to assign the values.
397 * <pre>
398 * SAXResult saxResult = sqlxml.setResult(SAXResult.class);
399 * ContentHandler contentHandler = saxResult.getXMLReader().getContentHandler();
400 * contentHandler.startDocument();
401 * // set the XML elements and attributes into the result
402 * contentHandler.endDocument();
403 * </pre>
404 *
405 * @param <T> the type of the class modeled by this Class object
406 * @param resultClass The class of the result, or null.
407 * If resultClass is null, a vendor specific Result implementation will be returned.
408 * The following classes are supported at a minimum:
409 * <pre>
410 * javax.xml.transform.dom.DOMResult - returns a DOMResult
411 * javax.xml.transform.sax.SAXResult - returns a SAXResult
412 * javax.xml.transform.stax.StAXResult - returns a StAXResult
413 * javax.xml.transform.stream.StreamResult - returns a StreamResult
414 * </pre>
415 * @return Returns a Result for setting the XML value.
416 * @throws SQLException if there is an error processing the XML value
417 * or if this feature is not supported.
418 * The getCause() method of the exception may provide a more detailed exception, for example,
419 * if an XML parser exception occurs.
420 * An exception is thrown if the state is not writable.
421 * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
422 * this method
423 * @since 1.6
424 */
425 <T extends Result> T setResult(Class<T> resultClass) throws SQLException;
|