Programmation à l'aide de SQLXML
Cette section explique comment utiliser les méthodes de l’API Pilote Microsoft JDBC pour SQL Server pour stocker et récupérer un document XML dans une base de données relationnelle avec des objets SQLXML.
Cette section contient également des informations sur les types d'objets SQLXML ; par ailleurs, elle dresse une liste des recommandations et limitations importantes relatives à l'utilisation des objets SQLXML.
Lecture et écriture de données XML à l'aide d'objets SQLXML
La liste suivante explique comment utiliser les méthodes de l’API Pilote Microsoft JDBC pour SQL Server pour lire et écrire des données XML avec des objets SQLXML :
Pour créer un objet SQLXML, utilisez la méthode createSQLXML de la classe SQLServerConnection. Notez que cette méthode crée un objet SQLXML sans aucune donnée. Pour ajouter des données xml à l’objet SQLXML, appelez l’une des méthodes suivantes spécifiées dans l’interface SQLXML : setResult, setCharacterStream, setBinaryStream ou setString.
Pour récupérer l’objet SQLXML proprement dit, utilisez les méthodes getSQLXML de la classe SQLServerResultSet ou de la classe SQLServerCallableStatement.
Pour récupérer les données xml à partir d’un objet SQLXML, utilisez l’une des méthodes suivantes spécifiées dans l’interface SQLXML : getSource, getCharacterStream, getBinaryStream ou getString.
Pour mettre à jour les données xml dans un objet SQLXML, utilisez la méthode updateSQLXML de la classe SQLServerResultSet.
Pour stocker un objet SQLXML dans une colonne de table de base de données de type xml, utilisez les méthodes setSQLXML de la classe SQLServerPreparedStatement ou de la classe SQLServerCallableStatement.
L'exemple de code de Exemple de type de données SQLXML montre comment effectuer ces tâches d'API courantes.
Objets SQLXML accessibles en lecture et en écriture
Le tableau suivant répertorie les types d'objets SQLXML pris en charge par les méthodes setter, getter et updater fournies par l'API JDBC. Les colonnes du tableau font référence aux éléments suivants :
La colonne Nom de la méthode liste les méthodes getter, setter et updater prises en charge dans l’API JDBC.
La colonne Objet SQLXML getter représente un objet SQLXML créé par la méthode getSQLXML de la classe SQLServerCallableStatement ou par la méthode getSQLXML de la classe SQLServerResultSet.
La colonne Objet SQLXML setter représente un objet SQLXML créé par la méthode createSQLXML de la classe SQLServerConnection. Notez que les méthodes setter ci-dessous acceptent seulement un objet SQLXML créé par la méthode createSQLXML.
| Nom de la méthode | Objet SQLXML getter (Accessible en lecture) |
Objet SQLXML setter (Accessible en écriture) |
|---|---|---|
| CallableStatement.setSQLXML() | Non pris en charge | Prise en charge |
| CallableStatement.setObject() | Non pris en charge | Prise en charge |
| PreparedStatement.setSQLXML() | Non pris en charge | Prise en charge |
| PreparedStatement.setObject() | Non pris en charge | Prise en charge |
| ResultSet.updateSQLXML() | Non pris en charge | Prise en charge |
| ResultSet.updateObject() | Non pris en charge | Prise en charge |
| ResultSet.getSQLXML() | Prise en charge | Non pris en charge |
| CallableStatement.getSQLXML() | Prise en charge | Non pris en charge |
Comme indiqué dans le tableau ci-dessus, les méthodes SQLXML setter ne fonctionnent pas avec les objets SQLXML accessibles en lecture ; de même, les méthodes getter ne fonctionnent pas avec les objets SQLXML accessibles en écriture.
Si l’application appelle la méthode setObject en spécifiant un paramètre d’échelle ou de longueur avec un objet SQLXML, ce paramètre d’échelle ou de longueur est ignoré.
Recommandations et limitations relatives à l'utilisation des objets SQLXML
Les applications peuvent utiliser des objets SQLXML pour lire et écrire les données XML dans la base de données. La liste suivante fournit des informations sur les limitations et recommandations spécifiques à l'utilisation d'objets SQLXML :
Un objet SQLXML ne peut être valide que pendant la durée de la transaction au cours de laquelle il a été créé.
Un objet SQLXML reçu à partir d'une méthode getter ne peut être utilisé que pour lire des données.
Un objet SQLXML créé par l'objet de connexion ne peut être utilisé que pour écrire des données.
L'application ne peut appeler qu'une seule méthode getter sur un objet SQLXML accessible en lecture pour lire des données. Une fois la méthode getter appelée, toutes les autres méthodes getter ou setter sur le même objet SQLXML échouent.
L’application ne peut appeler que la méthode free sur l’objet SQLXML, une fois qu’un accès en lecture ou en écriture a eu lieu sur ce dernier. Toutefois, il est toujours possible de traiter la source ou le flux retourné tant que la colonne ou le paramètre sous-jacent est actif. Si la colonne ou le paramètre sous-jacent devient inactif, la source ou le flux associé à l'objet SQLXML est fermé. Si la colonne ou le paramètre sous-jacent n'est plus valide, les données sous-jacentes ne sont pas disponibles pour les méthodes getter du flux, de SAX (Simple API for XML) et de StAX (Streaming API for XML).
L'application ne peut appeler qu'une seule méthode setter sur un objet SQLXML accessible en écriture. Une fois la méthode setter appelée, toutes les autres méthodes setter ou getter sur le même objet SQLXML échouent.
Pour définir des données sur l'objet SQLXML, l'application doit utiliser la méthode setter appropriée ainsi que les fonctions correspondantes dans l'objet retourné.
Les méthodes getSQLXML de la classe SQLServerCallableStatement et de la classe SQLServerResultSet retournent des données Null si la colonne sous-jacente est Null.
Les objets setter peuvent être valides via la connexion dans laquelle ils ont été créés.
Les applications ne sont pas autorisées à définir une valeur Null à l’aide des méthodes setter fournies par l’interface SQLXML. Les applications peuvent définir une chaîne vide ("") à l'aide des méthodes setter fournies dans l'interface SQLXML. Pour définir une valeur Null, les applications doivent appeler au choix :
les méthodes setNull de la classe SQLServerCallableStatement et de la classe SQLServerPreparedStatement ;
les méthodes setObject de la classe SQLServerCallableStatement et de la classe SQLServerPreparedStatement ;
les méthodes setSQLXML de la classe SQLServerCallableStatement et de la classe SQLServerPreparedStatement avec une valeur de paramètre Null.
Lors de l'utilisation de documents XML, il est recommandé de privilégier les analyseurs SAX (Simple API for XML) et StAX (Streaming API for XML) aux analyseurs DOM (Document Object Model) pour des raisons de performances.
Les analyseurs XML ne peuvent pas gérer les valeurs vides. Toutefois, SQL Server permet aux applications de récupérer et de stocker des valeurs vides dans les colonnes de base de données de type de données XML. En d'autres termes, lors de l'analyse des données XML, si la valeur sous-jacente est vide, une exception est levée par l'analyseur. Pour les sorties DOM, le pilote JDBC intercepte cette exception et génère une erreur. Pour les sorties SAX et Stax, l'erreur provient directement de l'analyseur.
Prise en charge de la mise en mémoire tampon adaptative et de SQLXML
Les flux de données aux formats binaire et caractère retournés par l'objet SQLXML obéissent aux modes de mise en mémoire tampon adaptative ou de mise en mémoire tampon complète. Par ailleurs, si les analyseurs XML ne sont pas des flux, ils n'obéissent pas aux paramètres de mise en mémoire tampon adaptative ou de mise en mémoire tampon complète. Pour plus d’informations sur la mise en mémoire tampon adaptative, consultez Utiliser la mise en mémoire tampon adaptative.