Programar con SQLXML
En esta sección se describe cómo usar los métodos de la API del Microsoft JDBC Driver para SQL Server para almacenar y recuperar un documento XML en y desde una base de datos relacional con objetos SQLXML.
Esta sección también contiene información acerca de los tipos de objetos SQLXML y proporciona una lista de las instrucciones y las limitaciones importantes cuando se usan objetos SQLXML.
Leer y escribir datos XML con objetos SQLXML
En la lista siguiente se describe cómo usar los métodos de la API del Microsoft JDBC Driver para SQL Server para leer y escribir datos XML con objetos SQLXML:
Para crear un objeto SQLXML, use el método createSQLXML de la clase SQLServerConnection. Tenga en cuenta que este método crea un objeto SQLXML sin dato alguno. Para agregar datos xml al objeto SQLXML, llame a uno de los siguientes métodos especificados en la interfaz SQLXML: setResult, setCharacterStream, setBinaryStream o setString.
Para recuperar el propio objeto SQLXML, use los métodos getSQLXML de la clase SQLServerResultSet o de la clase SQLServerCallableStatement.
Para recuperar los datos xml de un objeto SQLXML, use uno de los siguientes métodos especificados en la interfaz SQLXML: getSource, getCharacterStream, getBinaryStream o getString.
Para actualizar los datos xml de un objeto SQLXML, use el método updateSQLXML de la clase SQLServerResultSet.
Para almacenar un objeto SQLXML en una columna de tabla del tipo xml, use los métodos setSQLXML de la clase SQLServerPreparedStatement o de la clase SQLServerCallableStatement.
El código de ejemplo de Ejemplo de tipos de datos SQLXML muestra cómo realizar estas tareas de API comunes.
Objetos SQLXML de lectura y escritura
La tabla siguiente enumera qué tipos de objetos SQLXML son compatibles con los métodos establecedor, captador y actualizador de la API de JDBC. Las columnas de la tabla hacen referencia a lo siguiente:
La columna Nombre de método enumera los métodos compatibles establecedor, captador y actualizador de la API de JDBC.
La columna Objeto SQLXML de captador representa un objeto SQLXML que es creado bien por el método getSQLXML de la clase SQLServerCallableStatement o bien por el método getSQLXML de la clase SQLServerResultSet.
La columna Objeto SQLXML establecedor representa un objeto SQLXML que es creado por el método createSQLXML de la clase SQLServerConnection. Tenga en cuenta que los métodos establecedor que se indican abajo solamente aceptan un objeto SQLXML creado por el método createSQLXML.
| Nombre del método | Objeto SQLXML de captador (lectura) |
Objeto SQLXML establecedor (escritura) |
|---|---|---|
| CallableStatement.setSQLXML() | No compatible | Compatible |
| CallableStatement.setObject() | No compatible | Compatible |
| PreparedStatement.setSQLXML() | No compatible | Compatible |
| PreparedStatement.setObject() | No compatible | Compatible |
| ResultSet.updateSQLXML() | No compatible | Compatible |
| ResultSet.updateObject() | No compatible | Compatible |
| ResultSet.getSQLXML() | Compatible | No compatible |
| CallableStatement.getSQLXML() | Compatible | No compatible |
Tal como se muestra en el área superior, los métodos SQLXML establecedor no funcionarán con los objetos SQLXML de lectura; similarmente, los métodos captadores no funcionarán con los objetos SQLXML de escritura.
Si la aplicación invoca el método setObject especificando un parámetro de escala o de longitud con un objeto SQLXML, se ignora el parámetro de escala o de longitud.
Instrucciones y limitaciones al usar objetos SQLXML
Las aplicaciones pueden usar objetos SQLXML para leer datos XML de la base de datos y para escribirlos en ella. La lista siguiente proporciona información relativa a las instrucciones y limitaciones específicas durante el uso de objetos SQLXML.
Un objeto SQLXML solamente puede ser válido durante la transacción en la que se creó.
Un objeto SQLXML recibido de un método de captador solamente se puede usar para leer datos.
Un objeto SQLXML creado por el objeto de conexión solamente se puede usar para escribir datos.
La aplicación solamente puede invocar un método de captador en un objeto SQLXML de lectura para leer datos. Después de invocarse el método de captador, todos los demás métodos captador o establecedor del mismo objeto SQLXML dan error.
La aplicación solamente puede invocar el método free en el objeto SQLXML después de que se ha leído o escrito. Sin embargo, sigue siendo posible procesar el flujo o el origen devueltos mientras la columna o el parámetro subyacentes estén activos. Si la columna o el parámetro subyacentes están inactivos, el flujo o el origen asociados con el objeto SQLXML se cerrarán. Si la columna o el parámetro subyacentes ya no son válidos, los datos subyacentes ya no estarán disponibles para los métodos captadores de Stream, Simple API for XML (SAX) y de Streaming API for XML (StAX).
La aplicación solamente puede invocar un método establecedor en un objeto SQLXML de escritura. Después de invocarse el método establecedor, todos los demás métodos establecedor o captador del mismo objeto SQLXML dan error.
Para establecer datos en el objeto SQLXML, la aplicación debe usar las funciones y el método establecedor apropiados en el objeto devuelto.
Los métodos getSQLXML de la clase SQLServerCallableStatement y de la clase SQLServerResultSet devuelven datos null si la columna subyacente es null.
Los objetos establecedor pueden ser válidos durante la conexión en la que son creados.
A las aplicaciones no se les permite establecer un valor NULL utilizando los métodos establecedor proporcionados por la interfaz de SQLXML. Las aplicaciones pueden establecer un valor vacío ("") utilizando los métodos establecedor proporcionados por la interfaz de SQLXML. Para establecer un valor null, las aplicaciones deberían llamar a uno de los elementos siguientes:
Los métodos setNull de la clase SQLServerCallableStatement y de la clase SQLServerPreparedStatement.
Los métodos setObject de la clase SQLServerCallableStatement y de la clase SQLServerPreparedStatement.
Los métodos setSQLXML de la clase SQLServerCallableStatement y de la clase SQLServerPreparedStatement con un valor de parámetro null.
Al trabajar con documentos XML, recomendamos usar los analizadores Simple API for XML (SAX) y Streaming API for XML (StAX) en lugar de los analizadores de Document Object Model (DOM) por motivos de rendimiento.
Los analizadores XML no pueden controlar valores vacíos. Sin embargo, SQL Server permite que las aplicaciones recuperen valores vacíos de columnas de base de datos del tipo de datos XML y los almacenen en ellas. Eso significa que al analizar los datos XML, si el valor subyacente está vacío, el analizador devuelve una excepción. En los resultados de DOM, el controlador JDBC capta esa excepción y devuelve un error. En los resultados de SAX y Stax, el error procede directamente del analizador.
Almacenamiento en búfer adaptable y compatibilidad con SQLXML
Los flujos binarios y de caracteres devueltos por el objeto SQLXML obedecen a los modos de almacenamiento en búfer completo o adaptable. Por otra parte, si los analizadores XML no son secuencia, no obedecerán a los valores completos o adaptables. Para obtener más información acerca del almacenamiento en búfer adaptable, consulte Empleo de almacenamiento en búfer adaptable.