Programando com SQLXML
Esta seção descreve como usar os métodos da API Microsoft JDBC Driver para SQL Server para armazenar e recuperar um documento XML em um banco de dados relacional, ou vindo dele, com objetos SQLXML.
Além disso, ela contém informações sobre os tipos de objetos SQLXML e fornece uma lista de diretrizes e limitações importantes referentes ao uso desses objetos.
Lendo e escrevendo dados XML com objetos SQLXML
A lista a seguir descreve como usar os métodos da API Microsoft JDBC Driver para SQL Server para ler e gravar dados XML com objetos SQLXML:
Para criar um objeto SQLXML, use o método createSQLXML da classe SQLServerConnection. Observe que esse método cria um objeto SQLXML sem quaisquer dados. Para adicionar dados xml ao objeto SQLXML, chame um dos seguintes métodos especificados na interface do SQLXML: setResult, setCharacterStream, setBinaryStream ou setString.
Para recuperar o objeto SQLXML propriamente dito, use os métodos getSQLXML da classe SQLServerResultSet ou da classe SQLServerCallableStatement.
Para recuperar dados xml de um objeto SQLXML, use um dos seguintes métodos especificados na interface do SQLXML: getSource, getCharacterStream, getBinaryStream ou getString.
Para atualizar os dados xml em um objeto SQLXML, use o método updateSQLXML da classe SQLServerResultSet.
Para armazenar um objeto SQLXML em uma coluna de tabela de banco de dados do tipo xml, use os métodos setSQLXML da classe SQLServerPreparedStatement ou da classe SQLServerCallableStatement.
O código de exemplo em Exemplo de tipo de dados SQLXML demonstra como executar essas tarefas comuns da API.
Objetos SQLXML que podem ser lidos e escritos
A tabela a seguir relaciona os tipos de objetos SQLXML que têm suporte dos métodos de setter, getter e updater fornecidos pela API do JDBC. As colunas da tabela referem-se ao seguinte:
A coluna Nome do método lista os métodos de getter, setter e updater compatíveis com a API do JDBC.
A coluna Objeto SQLXML de getter representa um objeto SQLXML que é criado pelo método getSQLXML da classe SQLServerCallableStatement ou pelo método getSQLXML da classe SQLServerResultSet.
A coluna Objeto SQLXML de setter representa um objeto SQLXML que é criado pelo método createSQLXML da classe SQLServerConnection. Observe que os métodos de setter indicados abaixo só aceitam um objeto SQLXML criado pelo método createSQLXML.
| Nome do método | Objeto SQLXML de getter (pode ser lido) |
Objeto SQLXML de setter (gravável) |
|---|---|---|
| CallableStatement.setSQLXML() | Sem suporte | Com suporte |
| CallableStatement.setObject() | Sem suporte | Com suporte |
| PreparedStatement.setSQLXML() | Sem suporte | Com suporte |
| PreparedStatement.setObject() | Sem suporte | Com suporte |
| ResultSet.updateSQLXML() | Sem suporte | Com suporte |
| ResultSet.updateObject() | Sem suporte | Com suporte |
| ResultSet.getSQLXML() | Com suporte | Sem suporte |
| CallableStatement.getSQLXML() | Com suporte | Sem suporte |
Como mostrado na tabela acima, os métodos SQLXML de setter não funcionarão com os objetos SQLXML que podem ser lidos; da mesma forma, os métodos de getter não funcionarão com os objetos SQLXML que podem ser escritos.
Se o aplicativo invocar o método setObject especificando uma escala ou um parâmetro de tamanho com um objeto SQLXML, o parâmetro de escala ou tamanho será ignorado.
Diretrizes e limitações ao usar objetos SQLXML
Os aplicativos podem usar objetos SQLXML para ler e escrever os dados XML de e para o banco de dados. A lista a seguir fornece informações sobre limitações específicas e orientação quanto ao uso de objetos SQLXML:
Um objeto SQLXML só pode ser válido pela duração da transação em que foi criado.
Um objeto SQLXML recebido de um método de getter só pode ser usado para ler dados.
Um objeto SQLXML criado pelo objeto de conexão só pode ser usado para escrever dados.
O aplicativo só pode invocar um único método de getter em um objeto SQLXML legível para ler dados. Depois que o método de getter for invocado, ocorrerá falha em todos os outros métodos de getter ou setter no mesmo objeto SQLXML.
O aplicativo só pode invocar o método gratuito no objeto SQLXML depois que ele é lido ou gravado. Porém, ainda será possível processar a origem ou o fluxo retornado, contanto que a coluna ou o parâmetro subjacente esteja ativo. Se a coluna ou o parâmetro subjacente ficar inativo, a origem ou o fluxo associado com o objeto SQLXML será fechado. Se a coluna ou o parâmetro subjacente não for mais válido, os dados subjacentes não estarão disponíveis para os getters Fluxo, SAX (API Simples para XML) e StAX (API de Fluxo para XML).
O aplicativo só pode invocar um único método de setter em um objeto SQLXML que pode ser escrito. Depois que o método de setter for invocado, ocorrerá falha em todos os outros métodos de setter ou getter no mesmo objeto SQLXML.
Para definir dados no objeto SQLXML, o aplicativo deve usar o método de setter apropriado e as funções no objeto retornado.
Os métodos getSQLXML da classe SQLServerCallableStatement e da classe SQLServerResultSet retornarão dados null se a coluna subjacente for null.
Os objetos de setter poderão ser válidos através da conexão dentro da qual forem criados.
Os aplicativos não têm permissão para definir um valor null usando os métodos de setter fornecidos pela interface SQLXML. Os aplicativos podem definir uma cadeia de caracteres vazia ("") usando os métodos de setter fornecidos na interface SQLXML. Para definir um valor null, os aplicativos precisam chamar um dos seguintes itens:
Os métodos setNull das classes SQLServerCallableStatement e SQLServerPreparedStatement.
Os métodos setObject das classes SQLServerCallableStatement e SQLServerPreparedStatement.
Os métodos setSQLXML das classes SQLServerCallableStatement e SQLServerPreparedStatement com um valor de parâmetro null.
Ao trabalhar com documentos XML, recomenda-se usar os analisadores SAX (API Simples para XML) e StAX (API de Fluxo para XML) em vez dos analisadores DOM (Document Object Model), por razões de desempenho.
Os analisadores de XML não podem tratar valores vazios. Porém, o SQL Server permite que os aplicativos recuperem e armazenem valores vazios de e para colunas de banco de dados do tipo de dados XML. Isso significa que, ao analisar os dados XML, se o valor subjacente for vazio, uma exceção será lançada pelo analisador. Para saídas de DOM, o driver JDBC captura essa exceção e lança um erro. Para saídas de SAX e StAX, o erro vem diretamente do analisador.
Suporte a buffer adaptável e SQLXML
Os fluxos binário e de caracteres retornados pelo objeto SQLXML obedecem aos modos de buffer adaptável ou completo. Por outro lado, se os analisadores de XML não forem fluxos, eles não obedecerão às configurações de adaptável ou completo. Para obter mais informações sobre como usar o buffer adaptável, veja Como usar o buffer adaptável.