Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Bagian ini menjelaskan cara menggunakan metode Microsoft JDBC Driver for SQL Server API untuk menyimpan dan mengambil dokumen XML dalam dan dari database relasional dengan objek SQLXML .
Bagian ini juga berisi informasi tentang jenis objek SQLXML dan menyediakan daftar pedoman dan batasan penting saat menggunakan objek SQLXML.
Membaca dan menulis data XML dengan objek SQLXML
Daftar berikut ini menjelaskan cara menggunakan metode Microsoft JDBC Driver for SQL Server API untuk membaca dan menulis data XML dengan objek SQLXML:
Untuk membuat objek SQLXML, gunakan metode createSQLXML dari kelas SQLServerConnection . Perhatikan bahwa metode ini membuat objek SQLXML tanpa data apa pun. Untuk menambahkan data xml ke objek SQLXML, panggil salah satu metode berikut yang ditentukan dalam antarmuka SQLXML: setResult, setCharacterStream, setBinaryStream, atau setString.
Untuk mengambil objek SQLXML itu sendiri, gunakan metode getSQLXML dari kelas SQLServerResultSet atau kelas SQLServerCallableStatement .
Untuk mengambil data xml dari objek SQLXML, gunakan salah satu metode berikut yang ditentukan dalam antarmuka SQLXML: getSource, getCharacterStream, getBinaryStream, atau getString.
Untuk memperbarui data xml dalam objek SQLXML, gunakan metode updateSQLXML dari kelas SQLServerResultSet .
Untuk menyimpan objek SQLXML dalam kolom tabel database dari jenis xml, gunakan metode setSQLXML dari kelas SQLServerPreparedStatement atau kelas SQLServerCallableStatement .
Contoh kode dalam sampel jenis data SQLXML menunjukkan cara melakukan tugas API umum ini.
Objek SQLXML yang dapat dibaca dan dapat ditulis
Tabel berikut mencantumkan jenis objek SQLXML mana yang didukung oleh metode setter, getter, dan updater yang disediakan oleh JDBC API. Kolom dalam tabel merujuk ke yang berikut ini:
Kolom Nama Metode mencantumkan metode getter, setter, dan updater yang didukung di JDBC API.
Kolom Objek Getter SQLXML mewakili objek SQLXML, yang dibuat dengan metode getSQLXML dari kelas SQLServerCallableStatement atau metode getSQLXML dari kelas SQLServerResultSet .
Kolom Objek Setter SQLXML mewakili objek SQLXML, yang dibuat oleh metode createSQLXML dari kelas SQLServerConnection . Perhatikan bahwa metode setter di bawah ini hanya menerima objek SQLXML yang dibuat oleh metode createSQLXML .
| Nama Metode | Objek Getter SQLXML (Dapat dibaca) |
Setter Objek SQLXML (Bisa-tulis) |
|---|---|---|
| CallableStatement.setSQLXML() | Tidak Didukung | Didukung |
| CallableStatement.setObject() | Tidak Didukung | Didukung |
| PreparedStatement.setSQLXML() | Tidak Didukung | Didukung |
| PreparedStatement.setObject() | Tidak Didukung | Didukung |
| ResultSet.updateSQLXML() | Tidak Didukung | Didukung |
| ResultSet.updateObject() | Tidak Didukung | Didukung |
| ResultSet.getSQLXML() | Didukung | Tidak Didukung |
| CallableStatement.getSQLXML() | Didukung | Tidak Didukung |
Seperti yang ditunjukkan pada tabel di atas, metode SQLXML setter tidak akan berfungsi dengan objek SQLXML yang dapat dibaca; demikian pula, metode getter tidak akan berfungsi dengan objek SQLXML yang dapat ditulis.
Jika aplikasi memanggil metode setObject dengan menentukan parameter skala atau panjang dengan objek SQLXML, parameter skala atau panjang diabaikan.
Panduan dan batasan saat menggunakan objek SQLXML
Aplikasi dapat menggunakan objek SQLXML untuk membaca dan menulis data XML dari dan ke database. Daftar berikut ini menyediakan informasi tentang batasan dan panduan tertentu saat menggunakan objek SQLXML:
Objek SQLXML hanya dapat valid selama durasi transaksi di mana objek tersebut dibuat.
Objek SQLXML yang diterima dari metode getter hanya dapat digunakan untuk membaca data.
Objek SQLXML yang dibuat oleh objek koneksi hanya dapat digunakan untuk menulis data.
Aplikasi hanya dapat memanggil satu metode getter pada objek SQLXML yang dapat dibaca untuk membaca data. Setelah metode getter dipanggil, semua metode getter atau setter lainnya pada objek SQLXML yang sama gagal.
Aplikasi hanya dapat memanggil metode gratis pada objek SQLXML setelah dibaca atau ditulis. Namun, masih dimungkinkan untuk memproses aliran atau sumber yang dikembalikan selama kolom atau parameter yang mendasar aktif. Jika kolom atau parameter yang mendasar menjadi tidak aktif, aliran atau sumber yang terkait dengan objek SQLXML akan ditutup. Jika kolom atau parameter yang mendasar tidak lagi valid, data yang mendasar tidak akan tersedia untuk getter Stream, Simple API for XML (SAX), dan Streaming API untuk XML (StAX).
Aplikasi hanya dapat memanggil satu metode setter pada objek SQLXML yang dapat ditulis. Setelah metode setter dipanggil, semua metode setter atau getter lainnya pada objek SQLXML yang sama gagal.
Untuk mengatur data pada objek SQLXML, aplikasi harus menggunakan metode setter yang sesuai dan fungsi dalam objek yang dikembalikan.
Metode getSQLXML dari kelas SQLServerCallableStatement dan kelas SQLServerResultSet mengembalikan data null jika kolom yang mendasarinya null.
Objek setter dapat valid melalui koneksi tempat objek dibuat.
Aplikasi tidak diizinkan untuk mengatur nilai null dengan menggunakan metode setter yang disediakan oleh antarmuka SQLXML. Aplikasi dapat mengatur string kosong ("") dengan menggunakan metode setter yang disediakan di antarmuka SQLXML. Untuk mengatur nilai null , aplikasi harus memanggil salah satu hal berikut:
Metode setNull dari kelas SQLServerCallableStatement dan kelas SQLServerPreparedStatement .
Metode setObject dari kelas SQLServerCallableStatement dan kelas SQLServerPreparedStatement .
Metode setSQLXML dari kelas SQLServerCallableStatement dan kelas SQLServerPreparedStatement dengan nilai parameter null.
Saat bekerja dengan dokumen XML, sebaiknya gunakan parser Simple API for XML (SAX) dan Streaming API untuk XML (StAX) alih-alih pengurai Document Object Model (DOM) karena alasan performa.
Pengurai XML tidak dapat menangani nilai kosong. Namun, SQL Server memungkinkan aplikasi untuk mengambil dan menyimpan nilai kosong dari dan ke kolom database dari jenis data XML. Itu berarti bahwa saat mengurai data XML, jika nilai yang mendasar kosong, pengecualian dilemparkan oleh pengurai. Untuk output DOM, driver JDBC menangkap pengecualian itu dan melemparkan kesalahan. Untuk output SAX dan Stax, kesalahan berasal dari pengurai secara langsung.
Buffering adaptif dan dukungan SQLXML
Aliran biner dan karakter yang dikembalikan oleh objek SQLXML mematuhi mode buffering adaptif atau penuh. Di sisi lain, jika pengurai XML tidak mengalir, pengurai XML tidak akan mematuhi pengaturan adaptif atau penuh. Untuk informasi selengkapnya tentang buffering adaptif, lihat Menggunakan Buffering Adaptif.