Spec-Zone.ru › OpenJDK 21

Пакет java.sql

package java.sql
Предоставляет API для доступа к данным, хранящимся в источнике данных (обычно реляционной базе данных), с использованием языка программирования Java. Данный API включает в себя механизм, позволяющий динамически устанавливать различные драйверы для доступа к разным источникам данных. Хотя API JDBC в основном предназначен для передачи SQL-запросов в базу данных, он предоставляет возможность чтения и записи данных из любого источника данных с табличной структурой. Функциональность чтения/записи, доступная через группу интерфейсов javax.sql.RowSet, может быть настраиваемой для использования и обновления данных из электронных таблиц, плоских файлов или любого другого источника данных с табличной структурой.

Что включает в себя API JDBC 4.3

API JDBC 4.3 включает в себя пакет java.sql, называемый ядром API JDBC, и пакет javax.sql, называемый API необязательного пакета JDBC. Этот полный API JDBC включён в Java Standard Edition (Java SE) версии 7. Пакет javax.sql расширяет функциональность API JDBC, превращая его из клиентского API в серверный, и является неотъемлемой частью технологии Java Enterprise Edition (Java EE).

Версии

API JDBC 4.3 включает в себя все предыдущие версии API JDBC:
  • API JDBC 4.2
  • API JDBC 4.1
  • API JDBC 4.0
  • API JDBC 3.0
  • Ядро API JDBC 2.1
  • API необязательного пакета JDBC 2.0
    (Обратите внимание, что ядро API JDBC 2.1 и API необязательного пакета JDBC 2.0 вместе называются API JDBC 2.0.)
  • API JDBC 1.2
  • API JDBC 1.0

Классы, интерфейсы, методы, поля, конструкторы и исключения содержат теги "since", указывающие на время их появления в Java-платформе. Когда эти теги "since" используются в комментариях Javadoc для API JDBC, они указывают на следующее:

  • Since 9 — новые в API JDBC 4.3 и входят в платформу Java SE версии 9
  • Since 1.8 — новые в API JDBC 4.2 и входят в платформу Java SE версии 8
  • Since 1.7 — новые в API JDBC 4.1 и входят в платформу Java SE версии 7
  • Since 1.6 — новые в API JDBC 4.0 и входят в платформу Java SE версии 6
  • Since 1.4 — новые в API JDBC 3.0 и входят в платформу J2SE версии 1.4
  • Since 1.2 — новые в API JDBC 2.0 и входят в платформу J2SE версии 1.2
  • Since 1.1 или нет тега "since" — в оригинальном API JDBC 1.0 и входят в JDK версии 1.1

ПРИМЕЧАНИЕ: Многие новые функции являются необязательными; в связи с этим, существует определённая вариативность в драйверах и поддерживаемых ими функциях. Всегда проверяйте документацию вашего драйвера, чтобы убедиться в поддержке функции перед её использованием.

ПРИМЕЧАНИЕ: Класс SQLPermission был добавлен в релизе Java 2 SDK, Standard Edition, версии 1.3. Этот класс используется для предотвращения несанкционированного доступа к потоку регистрации, связанному с DriverManager, который может содержать информацию, такую как имена таблиц, данные столбцов и т. д.

Что содержит пакет java.sql

Пакет java.sql содержит API для следующих задач:
  • Установление соединения с базой данных через механизм DriverManager
    • DriverManager class — устанавливает соединение с драйвером
    • SQLPermission class — предоставляет разрешения, когда код, выполняющийся в среде Security Manager, например апплет, пытается настроить поток регистрации через DriverManager
    • Driver interface — предоставляет API для регистрации и подключения драйверов на основе технологии JDBC («JDBC-драйверы»); обычно используется только классом DriverManager
    • DriverPropertyInfo class — предоставляет свойства для JDBC-драйвера; не используется обычным пользователем
  • Отправка SQL-запросов в базу данных
    • Statement — используется для отправки основных SQL-запросов
    • PreparedStatement — используется для отправки подготовленных запросов или основных SQL-запросов (производный от Statement)
    • CallableStatement — используется для вызова хранимых процедур базы данных (производный от PreparedStatement)
    • Connection interface — предоставляет методы для создания запросов и управления соединениями и их свойствами
    • Savepoint — предоставляет контрольные точки в транзакции
  • Получение и обновление результатов запроса
    • ResultSet interface
  • Стандартные сопоставления SQL-типов с классами и интерфейсами языка программирования Java
    • Array interface — сопоставление для SQL ARRAY
    • Blob interface — сопоставление для SQL BLOB
    • Clob interface — сопоставление для SQL CLOB
    • Date class — сопоставление для SQL DATE
    • NClob interface — сопоставление для SQL NCLOB
    • Ref interface — сопоставление для SQL REF
    • RowId interface — сопоставление для SQL ROWID
    • Struct interface — сопоставление для SQL STRUCT
    • SQLXML interface — сопоставление для SQL XML
    • Time class — сопоставление для SQL TIME
    • Timestamp class — сопоставление для SQL TIMESTAMP
    • Types class — предоставляет константы для SQL-типов
  • Настройка сопоставления SQL-типа данных пользователя (UDT) с классом языка программирования Java
    • SQLData interface — определяет сопоставление UDT с экземпляром этого класса
    • SQLInput interface — предоставляет методы для чтения атрибутов UDT из потока
    • SQLOutput interface — предоставляет методы для записи атрибутов UDT обратно в поток
  • Метаданные
    • DatabaseMetaData interface — предоставляет информацию о базе данных
    • ResultSetMetaData interface — предоставляет информацию о столбцах объекта ResultSet
    • ParameterMetaData interface — предоставляет информацию о параметрах команд PreparedStatement
  • Исключения
    • SQLException — выбрасывается большинством методов при проблемах с доступом к данным и некоторыми методами по другим причинам
    • SQLWarning — выбрасывается для указания предупреждения
    • DataTruncation — выбрасывается для указания того, что данные могут быть усечены
    • BatchUpdateException — выбрасывается для указания того, что не все команды в пакетном обновлении были успешно выполнены

java.sql и javax.sql функции, представленные в API JDBC 4.3

  • Добавлена поддержка Sharding
  • Улучшен Connection для возможности предоставлять подсказки драйверу о начале или завершении запроса, независимой единицы работы
  • Улучшен DatabaseMetaData для определения поддержки фрагментации
  • Добавлен метод drivers к DriverManager для возвращения потока текущих загруженных и доступных JDBC-драйверов
  • Добавлена поддержка Statement для цитирования литералов и простых идентификаторов
  • Уточнённая версия Java SE, в которой методы устарели

java.sql и javax.sql функции, представленные в API JDBC 4.2

  • Добавлен перечисление JDBCType и интерфейс SQLType
  • Поддержка REF CURSORS в CallableStatement
  • DatabaseMetaData методы для возвращения максимального размера логического LOB и поддержки курсоров ссылок
  • Добавлена поддержка больших значений подсчёта обновлений

java.sql и javax.sql функции, представленные в API JDBC 4.1

  • Возможность использования объектов Connection, ResultSet и Statement с оператором try-with-resources
  • Добавлена поддержка в CallableStatement и ResultSet для указания типа Java для преобразования через метод getObject
  • DatabaseMetaData методы для возвращения псевдостолбцов и информации о том, всегда ли возвращается сгенерированный ключ
  • Добавлена поддержка в Connection для указания схемы базы данных, прерывания и ограничения времени физического соединения
  • Добавлена поддержка закрытия объекта Statement при закрытии зависимых объектов
  • Поддержка получения родительского регистратора для Driver, DataSource, ConnectionPoolDataSource и XADataSource

java.sql и javax.sql функции, представленные в API JDBC 4.0

  • Автоматическое обнаружение драйверов java.sql — больше не нужно загружать класс java.sql.Driver через Class.forName
  • Добавлена поддержка национальных наборов символов
  • Добавлена поддержка типа данных SQL:2003 XML
  • Улучшения SQLException — Добавлена поддержка цепочки причин; Добавлены новые SQLException для общих кодов значений класса SQLState
  • Улучшения функциональности Blob/Clob — Предоставлена поддержка создания и освобождения экземпляра Blob/Clob, а также добавлены дополнительные методы для повышения доступности
  • Добавлена поддержка доступа к SQL ROWID
  • Добавлена возможность доступа JDBC-приложения к экземпляру JDBC-ресурса, который был обернут поставщиком, обычно в среде приложений сервера или пула соединений.
  • Возможность получать уведомления о закрытии или признании недействительным JDBC-ресурса PreparedStatement, связанного с PooledConnection

java.sql и javax.sql функции, представленные в API JDBC 3.0

  • Пулы заявок — повторное использование заявок, связанных с подключением пула
  • Точки сохранения — позволяют откатить транзакцию до обозначенной точки сохранения
  • Свойства, определенные для ConnectionPoolDataSource — указывают, как следует пулить подключения
  • Метаданные для параметров объекта PreparedStatement
  • Возможность извлечения значений из автоматически сгенерированных столбцов
  • Возможность возврата нескольких объектов ResultSet из открытых одновременно объектов CallableStatement
  • Возможность идентификации параметров для объектов CallableStatement по имени и по индексу
  • ResultSet поддержка — возможность указать, следует ли держать курсоры открытыми или закрывать их по окончании транзакции
  • Возможность извлечения и обновления экземпляра структурированного SQL-типа, на который ссылается объект Ref
  • Возможность программно обновлять значения BLOB, CLOB, ARRAY, и REF.
  • Добавление типа данных java.sql.Types.DATALINK — позволяет драйверам JDBC получать доступ к объектам, хранящимся вне источника данных
  • Добавление метаданных для извлечения иерархий типов SQL

java.sql Функции, представленные в ядре API JDBC 2.1

  • Результирующие наборы со скроллированием — использование новых методов в интерфейсе ResultSet , которые позволяют перемещать курсор к определенной строке или к позиции, относящейся к текущей позиции
  • Партии обновлений
  • Программные обновления — использование методов обновления ResultSet
  • Новые типы данных — интерфейсы, отображающие типы данных SQL3
  • Пользовательское отображение пользовательских типов (UDT)
  • Разные функции, включая подсказки производительности, использование символьных потоков, полную точность для значений java.math.BigDecimal, дополнительную безопасность и поддержку часовых поясов в значениях дат, времени и метках времени.

javax.sql Функции, представленные в дополнительном пакете API JDBC 2.0

  • Интерфейс DataSource в качестве средства подключения. Java Naming and Directory Interface (JNDI) используется для регистрации объекта DataSource в службе именования и для его извлечения.
  • Подключения пулом — позволяющее использовать и повторно использовать подключения
  • Распределенные транзакции — позволяющие транзакции охватывать различные серверы СУБД
  • RowSet технология — предоставляющая удобный способ обработки и передачи данных

Настройка отображения UDT

Пользовательский тип данных (UDT), определенный в SQL, может быть сопоставлен с классом в языке программирования Java. Структурированный тип SQL или тип SQL DISTINCT являются UDT, которые могут быть настроены для сопоставления. Три шага настроят пользовательское сопоставление:
  1. Определение структурированного типа SQL или типа DISTINCT в SQL
  2. Определение класса в языке программирования Java, с которым будет сопоставлен SQL UDT. Этот класс должен реализовывать интерфейс SQLData.
  3. Внесение записи в карту типов объекта Connection, содержащую два элемента:
    • полное квалифицированное имя SQL UDT
    • объект Class для класса, реализующего интерфейс SQLData

При наличии этих элементов для UDT, вызов методов ResultSet.getObject или CallableStatement.getObject для этого UDT автоматически извлечет пользовательское сопоставление для него. Также метод PreparedStatement.setObject автоматически сопоставит объект обратно к его типу SQL для его сохранения в источнике данных.

Спецификация пакета

  • Спецификация JDBC 4.3

Связанная документация

  • Урок: Основы JDBC (Учебники Java > Доступ к базам данных JDBC)
  • «Руководство по API JDBC и справка, третье издание»
Класс Описание
Array
Сопоставление в языке программирования Java для типа SQL ARRAY.
BatchUpdateException
Подкласс SQLException, выбрасываемый при возникновении ошибки во время операции пакетного обновления.
Blob
Представление (отображение) в языке программирования Java значения SQL BLOB.
CallableStatement
Интерфейс, используемый для выполнения хранимых процедур SQL.
ClientInfoStatus
Перечисление для статуса причины, по которой свойство не может быть установлено с помощью вызова Connection.setClientInfo
Clob
Сопоставление в языке программирования Java для типа SQL CLOB.
Connection
Подключение (сессия) к определённой базе данных.
ConnectionBuilder
Построитель, созданный из объекта DataSource, используемый для установления соединения с базой данных, которую представляет объект data source.
DatabaseMetaData
Полная информация о базе данных в целом.
DataTruncation
Исключение, сбрасываемое как исключение DataTruncation (при записи) или сообщаемое как предупреждение DataTruncation (при чтении), когда значение данных неожиданно усечено по причинам, отличным от превышения MaxFieldSize.
Date
Тонкий оболочка вокруг значения в миллисекундах, позволяющая JDBC идентифицировать его как значение SQL DATE.
Driver
Интерфейс, который должен реализовывать каждый класс драйвера.
DriverAction
Интерфейс, который должен быть реализован, когда драйвер Driver хочет получать уведомления от DriverManager.
DriverManager
Основной сервис для управления набором JDBC драйверов.
DriverPropertyInfo
Свойства драйвера для установления соединения.
JDBCType
Определяет константы, используемые для идентификации общих типов SQL, называемых типами JDBC.
NClob
Сопоставление в языке программирования Java для типа SQL NCLOB.
ParameterMetaData
Объект, который можно использовать для получения информации о типах и свойствах для каждого маркера параметра в объекте PreparedStatement.
PreparedStatement
Объект, представляющий предварительно скомпилированное SQL-определение.
PseudoColumnUsage
Перечисление для использования псевдо/скрытых столбцов.
Ref
Сопоставление в языке программирования Java значения SQL REF, которое является ссылкой на значение SQL структурированного типа в базе данных.
ResultSet
Таблица данных, представляющая набор результатов базы данных, который обычно генерируется путём выполнения запроса к базе данных.
ResultSetMetaData
Объект, который можно использовать для получения информации о типах и свойствах столбцов в объекте ResultSet.
RowId
Представление (отображение) в языке программирования Java значения SQL ROWID.
RowIdLifetime
Перечисление для значений времени жизни RowId.
Savepoint
Представление точки сохранения, которая является точкой в текущей транзакции, на которую можно сослаться из метода Connection.rollback.
ShardingKey
Интерфейс, используемый для указания, что этот объект представляет собой фрагментационный ключ.
ShardingKeyBuilder
Построитель, созданный из объекта DataSource или XADataSource , используемый для создания ShardingKey с подключами поддерживаемых типов данных.
SQLClientInfoException
Подкласс SQLException, который выбрасывается, когда одно или несколько свойств клиентской информации не могут быть установлены на Connection.
SQLData
Интерфейс, используемый для пользовательского сопоставления типа SQL-определённого пользователем (UDT) с классом в языке программирования Java.
SQLDataException
Подкласс SQLException, выбрасываемый, когда значение SQLState равно '22', или в условиях, определённых поставщиком.
SQLException
Исключение, которое предоставляет информацию об ошибке доступа к базе данных или других ошибках.
SQLFeatureNotSupportedException
Подкласс SQLException, который выбрасывается, когда значение SQLState равно '0A' (значение равно 'ноль' A).
SQLInput
Поток ввода, содержащий поток значений, представляющих экземпляр SQL-структурированного типа или SQL-дискретного типа.
SQLIntegrityConstraintViolationException
Подкласс SQLException, выбрасываемый, когда значение SQLState равно '23', или в условиях, определённых поставщиком.
SQLInvalidAuthorizationSpecException
Подкласс SQLException, выбрасываемый, когда значение SQLState равно '28', или в условиях, определённых поставщиком.
SQLNonTransientConnectionException
Подкласс SQLException, выбрасываемый для значения SQLState '08', или в условиях, определённых поставщиком.
SQLNonTransientException
Подкласс SQLException, выбрасываемый, когда повторная попытка того же действия завершится неудачей, если причина SQLException не будет исправлена.
SQLOutput
Поток вывода для записи атрибутов типа, определённого пользователем, обратно в базу данных.
SQLPermission
Разрешение, которое SecurityManager проверит, когда код, выполняющий приложение с включенным SecurityManager, вызывает метод DriverManager.deregisterDriver, метод DriverManager.setLogWriter, метод DriverManager.setLogStream (устаревший), метод SyncFactory.setJNDIContext, метод SyncFactory.setLogger, метод Connection.setNetworkTimeout или метод Connection.abort.
SQLRecoverableException
Подкласс SQLException, выбрасываемый в ситуациях, когда ранее неудачная операция может иметь успех, если приложение выполняет некоторые шаги по восстановлению и повторяет всю транзакцию или, в случае распределённой транзакции, ветвь транзакции.
SQLSyntaxErrorException
Подкласс SQLException, выбрасываемый, когда значение SQLState равно '42', или в условиях, определённых поставщиком.
SQLTimeoutException
Подкласс SQLException, выбрасываемый, когда истекает время ожидания, указанное Statement.setQueryTimeout, DriverManager.setLoginTimeout, DataSource.setLoginTimeout,XADataSource.setLoginTimeout.
END_OF_DOCUMENT_MARKER
SQLTransactionRollbackException
Подкласс SQLException, выбрасываемый, когда значение SQLState равно '40' или при условиях, определённых поставщиком.
SQLTransientConnectionException
Подкласс SQLException для значения SQLState '08' или при условиях, определённых поставщиком.
SQLTransientException
Подкласс SQLException, который выбрасывается в ситуациях, когда ранее неудачная операция может быть выполнена успешно при повторном её запуске без вмешательства функциональности на уровне приложения.
SQLType
Объект, используемый для идентификации универсального типа SQL, называемого типом JDBC или типом данных, специфичным для поставщика.
SQLWarning
Исключение, предоставляющее информацию о предупреждениях доступа к базе данных.
SQLXML
Сопоставление в языке программирования JavaTM для типа SQL XML.
Statement
Объект, используемый для выполнения статического оператора SQL и возврата результатов, которые он производит.
Struct
Стандартное сопоставление в языке программирования Java для структурированного типа SQL.
Time
Тонкая оболочка вокруг класса java.util.Date, которая позволяет JDBC API определить это как значение SQL TIME.
Timestamp
Тонкая оболочка вокруг java.util.Date, которая позволяет JDBC API определить это как значение SQL TIMESTAMP.
Types
Класс, определяющий константы, используемые для идентификации универсальных типов SQL, называемых типами JDBC.
Wrapper
Интерфейс для классов JDBC, которые предоставляют возможность получения делегата, когда экземпляр является на самом деле прокси-классом.

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.sql/java/sql/package-summary.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API