Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Esta secção descreve como usar o Microsoft JDBC Driver para métodos da API SQL Server para armazenar e recuperar um documento XML dentro e a partir de uma base de dados relacional com objetos SQLXML .
Esta secção contém também informações sobre os tipos de objetos SQLXML e fornece uma lista de diretrizes e limitações importantes ao utilizar objetos SQLXML.
Leitura e escrita de dados XML com objetos SQLXML
A lista seguinte descreve como usar o Microsoft JDBC Driver para métodos da API SQL Server para ler e escrever dados XML com objetos SQLXML:
Para criar um objeto SQLXML, use o método createSQLXML da classe SQLServerConnection . Note que este 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 SQLXML: setResult, setCharacterStream, setBinaryStream ou setString.
Para recuperar o próprio objeto SQLXML, use os métodos getSQLXML da classe SQLServerResultSet ou da classe SQLServerCallableStatement .
Para recuperar os dados xml de um objeto SQLXML, utilize um dos seguintes métodos especificados na interface SQLXML: getSource, getCharacterStream, getBinaryStream ou getString.
Para atualizar os dados xml num objeto SQLXML, utilize o método updateSQLXML da classe SQLServerResultSet .
Para armazenar um objeto SQLXML numa coluna de tabela de base de dados do tipo xml, utilize os métodos setSQLXML da classe SQLServerPreparedStatement ou da classe SQLServerCallableStatement .
O código de exemplo no exemplo de tipo de dados SQLXML demonstra como realizar estas tarefas comuns da API.
Objetos SQLXML legíveis e graváveis
A tabela seguinte lista que tipos de objetos SQLXML são suportados pelos métodos setter, getter e updater fornecidos pela API JDBC. As colunas da tabela referem-se ao seguinte:
A coluna Nome do Método lista os métodos getter, setter e updater suportados na API JDBC.
A coluna Getter SQLXML Object representa um objeto SQLXML, que é criado pelo método getSQLXML da classe SQLServerCallableStatement ou pelo método getSQLXML da classe SQLServerResultSet .
A coluna Setter SQLXML Object representa um objeto SQLXML, criado pelo método createSQLXML da classe SQLServerConnection . Note que os métodos setter abaixo aceitam apenas um objeto SQLXML criado pelo método createSQLXML .
| Nome do método | Getter SQLXML Object (Legível) |
Setter SQLXML Objeto (Escrito) |
|---|---|---|
| CallableStatement.setSQLXML() | Não suportado | Suportado |
| CallableStatement.setObject() | Não suportado | Suportado |
| PreparedStatement.setSQLXML() | Não suportado | Suportado |
| PreparedStatement.setObject() | Não suportado | Suportado |
| ResultSet.updateSQLXML() | Não suportado | Suportado |
| ResultSet.updateObject() | Não suportado | Suportado |
| ResultSet.getSQLXML() | Suportado | Não suportado |
| CallableStatement.getSQLXML() | Suportado | Não suportado |
Como mostrado na tabela acima, os métodos SQLXML do setter não funcionam com os objetos SQLXML legíveis; de forma semelhante, os métodos getter não funcionam com os objetos SQLXML graváveis.
Se a aplicação invocar o método setObject especificando um parâmetro de escala ou comprimento com um objeto SQLXML, o parâmetro de escala ou comprimento é ignorado.
Diretrizes e limitações ao utilizar objetos SQLXML
As aplicações podem usar objetos SQLXML para ler e escrever os dados XML a partir e para a base de dados. A lista seguinte fornece informações sobre limitações específicas e orientações ao utilizar objetos SQLXML:
Um objeto SQLXML só pode ser válido durante a duração da transação em que foi criado.
Um objeto SQLXML recebido de um método getter só pode ser usado para ler dados.
Um objeto SQLXML criado pelo objeto de ligação só pode ser usado para escrever dados.
A aplicação só pode invocar um método getter num objeto SQLXML legível para ler dados. Depois de invocado o método getter, todos os outros métodos getter ou setter no mesmo objeto SQLXML falham.
A aplicação pode invocar apenas o método livre no objeto SQLXML depois de ele ser lido ou escrito. No entanto, ainda é possível processar o fluxo ou fonte retornado desde que a coluna ou parâmetro subjacente esteja ativo. Se a coluna ou parâmetro subjacente se tornar inativo, o fluxo ou fonte associado ao objeto SQLXML será fechado. Se a coluna ou o parâmetro subjacente deixar de ser válido, os dados subjacentes não estarão disponíveis para os getters Stream, Simple API for XML (SAX) e Streaming API for XML (StAX).
A aplicação só pode invocar um método setter num objeto SQLXML gravável. Depois de invocado o método setter, todos os outros métodos setter ou getter no mesmo objeto SQLXML falham.
Para definir dados no objeto SQLXML, a aplicação deve usar o método setter apropriado e as funções no objeto devolvido.
Os métodos getSQLXML da classe SQLServerCallableStatement e da classe SQLServerResultSet retornam dados nulos se a coluna subjacente for nula.
Os objetos setter podem ser válidos através da ligação em que são criados.
As aplicações não podem definir um valor nulo usando os métodos setter fornecidos pela interface SQLXML. As aplicações podem definir uma cadeia vazia ("") usando os métodos setter fornecidos na interface SQLXML. Para definir um valor nulo , as aplicações devem chamar um dos seguintes:
Os métodos setNull das classes SQLServerCallableStatement e SQLServerPreparedStatement .
Os métodos setObject das classes SQLServerCallableStatement e SQLServerPreparedStatement.
Os métodos setSQLXML da classe SQLServerCallableStatement e da classe SQLServerPreparedStatement, com um valor de parâmetro null.
Ao trabalhar com documentos XML, recomendamos o uso de analisadores Simple API for XML (SAX) e Streaming API for XML (StAX) em vez de analisadores Document Object Model (DOM) por razões de desempenho.
Os analisadores XML não conseguem lidar com valores vazios. No entanto, o SQL Server permite que aplicações recuperem e armazenem valores vazios de e para colunas de base de dados do tipo de dado XML. Isto significa que, ao analisar os dados XML, se o valor subjacente estiver vazio, o analisador lança uma exceção. Para saídas DOM, o driver JDBC apanha essa exceção e gera um erro. Para saídas SAX e Stax, o erro vem diretamente do parser.
Buffering adaptativo e suporte para SQLXML
Os fluxos binários e de caracteres devolvidos pelo objeto SQLXML obedecem aos modos adaptativo ou de buffering completo. Por outro lado, se os analisadores XML não forem fluxos, não obedecerão às definições adaptativas ou completas. Para mais informações sobre buffering adaptativo, consulte Utilização do Buffering Adaptativo.