Интерфейс подключения

Все суперинтерфейсы:: AutoCloseable, Wrapper

public interface Connection extends Wrapper, AutoCloseable

Подключение (сессия) к определённой базе данных. SQL-запросы выполняются и результаты возвращаются в контексте подключения.

Объект базы данных типа Connection может предоставлять информацию о своих таблицах, поддерживаемом синтаксисе SQL, хранимых процедурах, возможностях этого подключения и т. д. Эта информация извлекается с помощью метода getMetaData.

Примечание: При настройке подключения Connection приложения JDBC должны использовать соответствующий метод Connection, такой как setAutoCommit или setTransactionIsolation. Приложения не должны вызывать SQL-команды напрямую для изменения конфигурации подключения, если существует доступный метод JDBC. По умолчанию объект Connection находится в режиме автоматического подтверждения, что означает автоматическое подтверждение изменений после выполнения каждого запроса. Если режим автоматического подтверждения отключён, метод commit необходимо вызывать явно для подтверждения изменений; в противном случае изменения в базе данных не будут сохранены.

Новый объект Connection, созданный с помощью ядра API JDBC 2.1, имеет связанную с ним пустую карту типов. Пользователь может ввести пользовательское отображение для UDT в этой карте типов. Когда UDT извлекается из источника данных с помощью метода ResultSet.getObject, метод getObject проверит карту типов подключения, чтобы увидеть, есть ли запись для этого UDT. Если да, метод getObject сопоставит UDT с указанным классом. Если нет, UDT будет сопоставлен с использованием стандартного сопоставления.

Пользователь может создать новую карту типов, которая является объектом java.util.Map, добавить в неё запись и передать её методам java.sql, которые могут выполнять пользовательское сопоставление. В этом случае метод будет использовать заданную карту типов вместо карты, связанной с подключением.

Например, следующий фрагмент кода указывает, что SQL-тип ATHLETES будет сопоставлен с классом Athletes в языке программирования Java. Фрагмент кода извлекает карту типов для объекта Connection con, вставляет запись в неё и затем устанавливает карту типов с новой записью в качестве карты типов подключения.

      java.util.Map map = con.getTypeMap();
      map.put("mySchemaName.ATHLETES", Class.forName("Athletes"));
      con.setTypeMap(map);

С момента:

1.1

См. также:

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final int`	`TRANSACTION_NONE`	Константа, указывающая, что транзакции не поддерживаются.
`static final int`	`TRANSACTION_READ_COMMITTED`	Константа, указывающая, что грязные чтения предотвращены; невоспроизводимые чтения и призрачные чтения могут произойти.
`static final int`	`TRANSACTION_READ_UNCOMMITTED`	Константа, указывающая, что грязные чтения, невоспроизводимые чтения и призрачные чтения могут произойти.
`static final int`	`TRANSACTION_REPEATABLE_READ`	Константа, указывающая, что грязные чтения и невоспроизводимые чтения предотвращены; призрачные чтения могут произойти.
`static final int`	`TRANSACTION_SERIALIZABLE`	Константа, указывающая, что грязные чтения, невоспроизводимые чтения и призрачные чтения предотвращены.

END_OF_DOCUMENT_MARKER

Краткое описание методов

Модификатор и тип	Метод	Описание
`void`	`abort(Executor executor)`	Закрывает открытое соединение.
`default void`	`beginRequest()`	Подсказывает драйверу, что запрос, независимая единица работы, начинается в этом соединении.
`void`	`clearWarnings()`	Очищает все предупреждения, сообщенные для этого объекта `Connection`.
`void`	`close()`	Освобождает базу данных и JDBC ресурсы этого объекта `Connection` немедленно, вместо ожидания их автоматического освобождения.
`void`	`commit()`	Делает все изменения, внесенные с момента предыдущего сохранения/отката, постоянными и освобождает все блокировки базы данных, в данный момент удерживаемые этим объектом `Connection`.
`Array`	`createArrayOf(String typeName, Object[] elements)`	Метод-фабрика для создания объектов Array.
`Blob`	`createBlob()`	Создает объект, реализующий интерфейс `Blob`.
`Clob`	`createClob()`	Создает объект, реализующий интерфейс `Clob`.
`NClob`	`createNClob()`	Создает объект, реализующий интерфейс `NClob`.
`SQLXML`	`createSQLXML()`	Создает объект, реализующий интерфейс `SQLXML`.
`Statement`	`createStatement()`	Создает объект `Statement` для отправки SQL-запросов в базу данных.
`Statement`	`createStatement(int resultSetType, int resultSetConcurrency)`	Создает объект `Statement`, который будет генерировать объекты `ResultSet` с заданным типом и конкурентностью.
`Statement`	`createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)`	Создает объект `Statement`, который будет генерировать объекты `ResultSet` с заданным типом, конкурентностью и удержанием.
`Struct`	`createStruct(String typeName, Object[] attributes)`	Метод-фабрика для создания объектов Struct.
`default void`	`endRequest()`	Подсказывает драйверу, что запрос, независимая единица работы, завершена.
`boolean`	`getAutoCommit()`	Возвращает текущий режим автоматического подтверждения для этого объекта `Connection`.
`String`	`getCatalog()`	Возвращает текущее имя каталога объекта `Connection`.
`Properties`	`getClientInfo()`	Возвращает список, содержащий имя и текущее значение каждого свойства информации клиента, поддерживаемого драйвером.
`String`	`getClientInfo(String name)`	Возвращает значение свойства информации клиента, заданного именем.
`int`	`getHoldability()`	Возвращает текущее значение удержания объектов `ResultSet`, созданных с использованием этого объекта `Connection`.
`DatabaseMetaData`	`getMetaData()`	Возвращает объект `DatabaseMetaData`, содержащий метаданные о базе данных, к которой это объект `Connection` представляет соединение.
`int`	`getNetworkTimeout()`	Возвращает количество миллисекунд, которые драйвер будет ждать завершения запроса к базе данных.
`String`	`getSchema()`	Возвращает текущее имя схемы объекта `Connection`.
`int`	`getTransactionIsolation()`	Возвращает текущий уровень изоляции транзакции объекта `Connection`.
`Map<String,Class<?>>`	`getTypeMap()`	Возвращает объект `Map`, связанный с этим объектом `Connection`.
`SQLWarning`	`getWarnings()`	Возвращает первое предупреждение, сообщенное вызовами на этом объекте `Connection`.
`boolean`	`isClosed()`	Возвращает, закрыт ли этот объект `Connection`.
`boolean`	`isReadOnly()`	Возвращает, находится ли этот объект `Connection` в режиме только для чтения.
`boolean`	`isValid(int timeout)`	Возвращает true, если соединение не закрыто и все еще валидно.
`String`	`nativeSQL(String sql)`	Преобразует заданный SQL-запрос в системную родную грамматику SQL.
`CallableStatement`	`prepareCall(String sql)`	Создает объект `CallableStatement` для вызова хранимых процедур базы данных.
`CallableStatement`	`prepareCall(String sql, int resultSetType, int resultSetConcurrency)`	Создает объект `CallableStatement`, который будет генерировать объекты `ResultSet` с заданным типом и конкурентностью.
`CallableStatement`	`prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)`	Создает объект `CallableStatement`, который будет генерировать объекты `ResultSet` с заданным типом и конкурентностью.
`PreparedStatement`	`prepareStatement(String sql)`	Создает объект `PreparedStatement` для отправки параметризованных SQL-запросов в базу данных.
`PreparedStatement`	`prepareStatement(String sql, int autoGeneratedKeys)`	Создает стандартный объект `PreparedStatement`, способный извлекать автоматически сгенерированные ключи.
`PreparedStatement`	`prepareStatement(String sql, int[] columnIndexes)`	Создает стандартный объект `PreparedStatement`, способный возвращать автоматически сгенерированные ключи, обозначенные заданным массивом.
`PreparedStatement`	`prepareStatement(String sql, int resultSetType, int resultSetConcurrency)`	Создает объект `PreparedStatement`, который будет генерировать объекты `ResultSet` с заданным типом и конкурентностью.
`PreparedStatement`	`prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)`	Создает объект `PreparedStatement`, который будет генерировать объекты `ResultSet` с заданным типом, конкурентностью и удержанием.
`PreparedStatement`	`prepareStatement(String sql, String[] columnNames)`	Создает стандартный объект `PreparedStatement`, способный возвращать автоматически сгенерированные ключи, обозначенные заданным массивом.
`void`	`releaseSavepoint(Savepoint savepoint)`	Удаляет указанный объект `Savepoint` и последующие объекты `Savepoint` из текущей транзакции.
`void`	`rollback()`	Отменяет все изменения, внесенные в текущей транзакции, и освобождает все блокировки базы данных, в данный момент удерживаемые этим объектом `Connection`.
`void`	`rollback(Savepoint savepoint)`	Отменяет все изменения, внесенные после установки данного объекта `Savepoint`.
`void`	`setAutoCommit(boolean autoCommit)`	Устанавливает режим автоматического подтверждения этого соединения в заданное состояние.
`void`	`setCatalog(String catalog)`	Устанавливает заданное имя каталога для выбора подпространства базы данных этого объекта `Connection`, в котором необходимо работать.
`void`	`setClientInfo(String name, String value)`	Устанавливает значение свойства информации клиента, заданного именем, в значение, указанное значением.
`void`	`setClientInfo(Properties properties)`	Устанавливает значения свойств информации клиента соединения.
`void`	`setHoldability(int holdability)`	Изменяет значение удержания по умолчанию для объектов `ResultSet`, созданных с помощью этого объекта `Connection`, на заданное значение удержания.
`void`	`setNetworkTimeout(Executor executor, int milliseconds)`	Устанавливает максимальный период ожидания объекта `Connection` или объектов, созданных из объекта `Connection`, ответа базы данных на любой один запрос.
`void`	`setReadOnly(boolean readOnly)`	Переводит это соединение в режим только для чтения как подсказка драйверу для включения оптимизаций базы данных.
`Savepoint`	`setSavepoint()`	Создает безымянный контрольный пункт в текущей транзакции и возвращает новый объект `Savepoint`, который его представляет.
`Savepoint`	`setSavepoint(String name)`	Создает контрольный пункт с заданным именем в текущей транзакции и возвращает новый объект `Savepoint`, который его представляет.
`void`	`setSchema(String schema)`	Устанавливает заданное имя схемы для доступа.
`default void`	`setShardingKey(ShardingKey shardingKey)`	Указывает shardingKey для использования с этим соединением

`default void`	`setShardingKey(ShardingKey shardingKey, ShardingKey superShardingKey)`	Устанавливает shardingKey и superShardingKey для подключения.
`default boolean`	`setShardingKeyIfValid(ShardingKey shardingKey, int timeout)`	Устанавливает и проверяет ключ фрагментации для этого подключения.
`default boolean`	`setShardingKeyIfValid(ShardingKey shardingKey, ShardingKey superShardingKey, int timeout)`	Устанавливает и проверяет ключи фрагментации для этого подключения.
`void`	`setTransactionIsolation(int level)`	Попытка изменить уровень изоляции транзакций для этого объекта на заданный.
`void`	`setTypeMap(Map<String,Class<?>> map)`	Устанавливает указанный объект в качестве карты типов для этого объекта.

Методы, объявленные в интерфейсе java.sql.Wrapper

isWrapperFor, unwrap

Подробное описание полей

TRANSACTION_NONE

static final int TRANSACTION_NONE

Постоянная, указывающая на то, что транзакции не поддерживаются.

См. также:

TRANSACTION_READ_UNCOMMITTED

static final int TRANSACTION_READ_UNCOMMITTED

Постоянная, указывающая, что могут возникнуть грязные чтения, невоспроизводимые чтения и фантомные чтения. Этот уровень допускает чтение строки, изменённой одной транзакцией, другой транзакцией до того, как изменения в этой строке будут подтверждены (``грязное чтение''). Если какие-либо изменения отменены, вторая транзакция получит недействительную строку.

См. также:

TRANSACTION_READ_COMMITTED

static final int TRANSACTION_READ_COMMITTED

Постоянная, указывающая, что грязные чтения предотвращаются; могут возникнуть невоспроизводимые чтения и фантомные чтения. Этот уровень предотвращает чтение транзакцией строки с незавершенными изменениями.

См. также:

TRANSACTION_REPEATABLE_READ

static final int TRANSACTION_REPEATABLE_READ

Постоянная, указывающая, что грязные чтения и невоспроизводимые чтения предотвращаются; могут возникнуть фантомные чтения. Этот уровень предотвращает чтение транзакцией строки с незавершенными изменениями, а также ситуацию, когда одна транзакция читает строку, вторая транзакция изменяет строку, а первая транзакция повторно читает строку, получая разные значения во второй раз (``невоспроизводимое чтение'').

См. также:

TRANSACTION_SERIALIZABLE

static final int TRANSACTION_SERIALIZABLE

Постоянная, указывающая, что грязные чтения, невоспроизводимые чтения и фантомные чтения предотвращаются. Этот уровень включает запреты в TRANSACTION_REPEATABLE_READ и дополнительно запрещает ситуацию, когда одна транзакция читает все строки, удовлетворяющие условию WHERE, вторая транзакция вставляет строку, удовлетворяющую этому условию WHERE, а первая транзакция повторно читает по тому же условию, получая дополнительную «фантомную» строку во втором чтении.

См. также:

Подробное описание методов

createStatement

Statement createStatement() throws SQLException

Создаёт объект для отправки SQL-запросов в базу данных. SQL-запросы без параметров обычно выполняются с использованием объектов Statement. Если один и тот же SQL-запрос выполняется многократно, использование объекта PreparedStatement может быть более эффективным.

Наборы результатов, созданные с помощью возвращённого объекта Statement, по умолчанию будут типа TYPE_FORWARD_ONLY и иметь уровень параллельности CONCUR_READ_ONLY. Уровень удерживания созданных наборов результатов можно определить, вызвав getHoldability().

Возвращает:: новый объект Statement по умолчанию
Исключения:: SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении

prepareStatement

PreparedStatement prepareStatement(String sql) throws SQLException

Создаёт объект для отправки параметризованных SQL-запросов в базу данных.

SQL-запрос с параметрами или без них может быть предварительно скомпилирован и сохранён в объекте PreparedStatement. Этот объект затем может быть использован для эффективного многократного выполнения этого запроса.

Примечание: Этот метод оптимизирован для обработки параметризованных SQL-запросов, которые извлекают выгоду из предварительной компиляции. Если драйвер поддерживает предварительную компиляцию, метод prepareStatement отправит запрос в базу данных для предварительной компиляции. Некоторые драйверы могут не поддерживать предварительную компиляцию. В этом случае запрос может не быть отправлен в базу данных до выполнения объекта PreparedStatement. Это не влияет напрямую на пользователей; однако это влияет на то, какие методы выбрасывают определённые SQLException объекты.

Наборы результатов, созданные с помощью возвращённого объекта PreparedStatement, по умолчанию будут типа TYPE_FORWARD_ONLY и иметь уровень параллельности CONCUR_READ_ONLY. Уровень удерживания созданных наборов результатов можно определить, вызвав getHoldability().

Параметры:: sql - SQL-запрос, который может содержать один или более заполнительных параметров «?»
Возвращает:: новый объект PreparedStatement по умолчанию, содержащий предварительно скомпилированный SQL-запрос
Исключения:: SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении

prepareCall

CallableStatement prepareCall(String sql) throws SQLException

Создаёт объект для вызова хранимых процедур базы данных. Объект CallableStatement предоставляет методы для настройки параметров IN и OUT и методы для выполнения вызова хранимой процедуры.

Примечание: Этот метод оптимизирован для обработки вызовов хранимых процедур. Некоторые драйверы могут отправить запрос на вызов в базу данных, когда метод prepareCall завершит работу; другие могут подождать до выполнения объекта CallableStatement. Это не влияет напрямую на пользователей; однако это влияет на то, какие методы выбрасывают определённые SQLException.

Наборы результатов, созданные с помощью возвращённого объекта CallableStatement, по умолчанию будут типа TYPE_FORWARD_ONLY и иметь уровень параллельности CONCUR_READ_ONLY. Уровень удерживания созданных наборов результатов можно определить, вызвав getHoldability().

Параметры:: sql - SQL-запрос, который может содержать один или более заполнителей параметров «?» Типично, этот запрос указывается с использованием синтаксиса JDBC для вызовов.
Возвращает:: новый объект CallableStatement по умолчанию, содержащий предварительно скомпилированный SQL-запрос
Исключения:: SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении

nativeSQL

String nativeSQL(String sql) throws SQLException

Преобразует данный SQL-запрос в системную собственную SQL-грамматику. Драйвер может преобразовать JDBC SQL-грамматику в собственную системную SQL-грамматику перед отправкой. Этот метод возвращает собственный вид запроса, который драйвер отправил бы.

Параметры:: sql - SQL-запрос, который может содержать один или более заполнителей параметров «?»
Возвращает:: собственный вид этого запроса
Исключения:: SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении

setAutoCommit

void setAutoCommit(boolean autoCommit) throws SQLException

Устанавливает режим автоматического подтверждения соединения в указанное состояние. Если соединение находится в режиме автоматического подтверждения, все его SQL-запросы будут выполняться и подтверждаться как отдельные транзакции. В противном случае SQL-запросы группируются в транзакции, которые завершаются вызовом метода commit или метода rollback. По умолчанию новые соединения находятся в режиме автоматического подтверждения.

Подтверждение происходит при завершении запроса. Время завершения запроса зависит от типа SQL-запроса:

Для операторов DML, таких как Insert, Update или Delete, и операторов DDL запрос завершается, как только он завершит выполнение.
Для операторов Select запрос завершается, когда связанный набор результатов закрывается.
Для объектов CallableStatement или для запросов, возвращающих несколько результатов, запрос завершается, когда все связанные наборы результатов закрыты, и все счётчики обновлений и параметры вывода получены.

ПРИМЕЧАНИЕ: Если этот метод вызывается во время транзакции и режим автоматического подтверждения изменяется, транзакция подтверждается. Если вызывается setAutoCommit, и режим автоматического подтверждения не изменяется, вызов является пустым.

Параметры:

autoCommit - true для включения режима автоматического подтверждения; false для его отключения

Исключения:

SQLException - если произошла ошибка доступа к базе данных, вызывается setAutoCommit(true) во время участия в распределённой транзакции или этот метод вызывается на закрытом соединении

См. также:

getAutoCommit

boolean getAutoCommit() throws SQLException

Возвращает текущий режим автоматического подтверждения для этого объекта Connection.

Возвращает:

текущее состояние режима автоматического подтверждения этого объекта Connection

Исключения:

SQLException - если произошла ошибка доступа к базе данных или этот метод вызывается на закрытом соединении

См. также:

commit

void commit() throws SQLException

Делает все изменения, внесённые с момента предыдущего commit/отката, постоянными и освобождает любые блокировки базы данных, в настоящее время удерживаемые этим Connection объектом. Этот метод следует использовать только при отключённом режиме автоматического подтверждения.

Throws:

SQLException - если произошла ошибка доступа к базе данных, этот метод вызван во время участия в распределённой транзакции, если этот метод вызван на закрытом соединении или этот Connection объект находится в режиме автоматического подтверждения

See Also:

rollback

void rollback() throws SQLException

Отменяет все изменения, внесённые в текущей транзакции, и освобождает любые блокировки базы данных, в настоящее время удерживаемые этим Connection объектом. Этот метод следует использовать только при отключённом режиме автоматического подтверждения.

Throws:

SQLException - если произошла ошибка доступа к базе данных, этот метод вызван во время участия в распределённой транзакции, этот метод вызван на закрытом соединении или этот Connection объект находится в режиме автоматического подтверждения

See Also:

close

void close() throws SQLException

Освобождает ресурсы базы данных и JDBC этого Connection объекта немедленно вместо ожидания их автоматического освобождения.

Вызов метода close на Connection объекте, который уже закрыт, является бесполезным действием.

Сильно рекомендуется, чтобы приложение явно подтверждало или отменяло активную транзакцию перед вызовом метода close. Если метод close вызывается и существует активная транзакция, результаты определяются реализацией.

Specified by:: close в интерфейсе AutoCloseable
Throws:: SQLException - если произошла ошибка доступа к базе данных

isClosed

boolean isClosed() throws SQLException

Возвращает значение, указывающее, был ли закрыт этот Connection объект. Соединение закрыто, если для него был вызван метод close или произошли определённые фатальные ошибки. Этот метод гарантированно вернёт true только при вызове после вызова метода Connection.close.

Этот метод обычно не используется для определения того, является ли подключение к базе данных валидным или невалидным. Типичный клиент может определить, что подключение невалидно, перехватив любые исключения, которые могут быть выброшены при попытке выполнения операции.

Returns:: true, если этот Connection объект закрыт; false, если он всё ещё открыт
Throws:: SQLException - если произошла ошибка доступа к базе данных

getMetaData

DatabaseMetaData getMetaData() throws SQLException

Возвращает объект DatabaseMetaData, содержащий метаданные о базе данных, к которой это Connection объект представляет подключение. Метаданные включают информацию о таблицах базы данных, поддерживаемом синтаксисе SQL, хранимых процедурах, возможностях этого подключения и т. д.

Returns:: объект DatabaseMetaData для этого Connection объекта
Throws:: SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении

setReadOnly

void setReadOnly(boolean readOnly) throws SQLException

Переводит это подключение в режим только для чтения как подсказка драйверу для включения оптимизаций базы данных.

Примечание: Этот метод не может быть вызван во время транзакции.

Parameters:: readOnly - true включает режим только для чтения; false отключает его
Throws:: SQLException - если произошла ошибка доступа к базе данных, этот метод вызван на закрытом соединении или этот метод вызван во время транзакции

isReadOnly

boolean isReadOnly() throws SQLException

Возвращает значение, указывающее, находится ли этот Connection объект в режиме только для чтения.

Returns:: true, если этот Connection объект находится в режиме только для чтения; false в противном случае
Throws:: SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении

setCatalog

void setCatalog(String catalog) throws SQLException

Устанавливает указанное имя каталога, чтобы выбрать подпространство базы данных этого Connection объекта для работы.

Если драйвер не поддерживает каталоги, он проигнорирует этот запрос.

Вызов метода setCatalog не влияет на ранее созданные или подготовленные Statement объекты. Определяется реализацией, происходит ли операция подготовки DBMS немедленно при вызове метода Connection или prepareCall. Для максимальной переносимости метод setCatalog следует вызывать перед созданием или подготовкой Statement.

Parameters:

catalog - имя каталога (подпространства в базе данных этого Connection объекта), в котором нужно работать

Throws:

SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении

See Also:

getCatalog

String getCatalog() throws SQLException

Возвращает текущее имя каталога этого Connection объекта.

Returns:

текущее имя каталога или null, если его нет

Throws:

SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении

See Also:

setTransactionIsolation

void setTransactionIsolation(int level) throws SQLException

Пытается изменить уровень изоляции транзакции для этого Connection объекта на заданный. Постоянные значения, определённые в интерфейсе Connection, представляют возможные уровни изоляции транзакций.

Примечание: Если этот метод вызывается во время транзакции, результат зависит от реализации.

Parameters:

level - одно из следующих Connection констант: Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ или Connection.TRANSACTION_SERIALIZABLE. (Обратите внимание, что Connection.TRANSACTION_NONE не может быть использовано, так как оно указывает, что транзакции не поддерживаются.)

Throws:

SQLException - если произошла ошибка доступа к базе данных, этот метод вызван на закрытом соединении или заданный параметр не является одной из Connection констант

See Also:

getTransactionIsolation

int getTransactionIsolation() throws SQLException

Возвращает текущий уровень изоляции транзакции для этого Connection объекта.

Returns:

текущий уровень изоляции транзакции, который будет одной из следующих констант: Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, Connection.TRANSACTION_SERIALIZABLE или Connection.TRANSACTION_NONE.

Throws:

SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении

See Also:

getWarnings

SQLWarning getWarnings() throws SQLException

Возвращает первое сообщение об ошибке, полученное в результате вызовов этого Connection объекта. Если сообщений об ошибках более одного, последующие ошибки будут присоединены к первой и могут быть получены путём вызова метода SQLWarning.getNextWarning на ошибке, которая была ранее получена.

Этот метод не может быть вызван на закрытом соединении; при этом будет брошено исключение SQLException.

Примечание: Последующие сообщения об ошибках будут присоединены к этому объекту SQLWarning.

Returns:

первый объект SQLWarning или null, если их нет

Throws:

SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении

See Also:

clearWarnings

void clearWarnings() throws SQLException

Очищает все предупреждения, полученные для этого Connection объекта. После вызова этого метода метод getWarnings возвращает null до тех пор, пока новое предупреждение не будет получено для этого Connection объекта.

Throws:: SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении

createStatement

Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException

Создаёт объект Statement, который будет генерировать объекты ResultSet с заданным типом и конкурентностью. Этот метод аналогичен методу createStatement выше, но позволяет переопределить тип и конкурентность набора результатов по умолчанию. Удерживаемость созданных наборов результатов можно определить, вызвав getHoldability().

Параметры:: resultSetType - тип набора результатов; один из ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE или ResultSet.TYPE_SCROLL_SENSITIVE; resultSetConcurrency - тип конкурентности; один из ResultSet.CONCUR_READ_ONLY или ResultSet.CONCUR_UPDATABLE
Возвращает:: новый объект Statement, который будет генерировать объекты ResultSet с заданным типом и конкурентностью
Выбрасывает:: SQLException - если происходит ошибка доступа к базе данных, этот метод вызывается на закрытом соединении или заданные параметры не являются ResultSet константами, указывающими тип и конкурентность; SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод или этот метод не поддерживается для указанного типа набора результатов и конкурентности набора результатов.
С:: 1.2

prepareStatement

PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency) throws SQLException

Создаёт объект PreparedStatement, который будет генерировать объекты ResultSet с заданным типом и конкурентностью. Этот метод аналогичен методу prepareStatement выше, но позволяет переопределить тип и конкурентность набора результатов по умолчанию. Удерживаемость созданных наборов результатов можно определить, вызвав getHoldability().

Параметры:: sql - объект String, представляющий SQL-запрос, который будет отправлен в базу данных; может содержать один или более параметров '?';; resultSetType - тип набора результатов; один из ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE или ResultSet.TYPE_SCROLL_SENSITIVE; resultSetConcurrency - тип конкурентности; один из ResultSet.CONCUR_READ_ONLY или ResultSet.CONCUR_UPDATABLE
Возвращает:: новый объект PreparedStatement, содержащий предварительно скомпилированный SQL-запрос, который будет генерировать объекты ResultSet с заданным типом и конкурентностью
Выбрасывает:: SQLException - если происходит ошибка доступа к базе данных, этот метод вызывается на закрытом соединении или заданные параметры не являются ResultSet константами, указывающими тип и конкурентность; SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод или этот метод не поддерживается для указанного типа набора результатов и конкурентности набора результатов.
С:: 1.2

prepareCall

CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency) throws SQLException

Создаёт объект CallableStatement, который будет генерировать объекты ResultSet с заданным типом и конкурентностью. Этот метод аналогичен методу prepareCall выше, но позволяет переопределить тип и конкурентность набора результатов по умолчанию. Удерживаемость созданных наборов результатов можно определить, вызвав getHoldability().

Параметры:: sql - объект String, представляющий SQL-запрос, который будет отправлен в базу данных; может содержать один или более параметров '?';; resultSetType - тип набора результатов; один из ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE или ResultSet.TYPE_SCROLL_SENSITIVE; resultSetConcurrency - тип конкурентности; один из ResultSet.CONCUR_READ_ONLY или ResultSet.CONCUR_UPDATABLE
Возвращает:: новый объект CallableStatement, содержащий предварительно скомпилированный SQL-запрос, который будет генерировать объекты ResultSet с заданным типом и конкурентностью
Выбрасывает:: SQLException - если происходит ошибка доступа к базе данных, этот метод вызывается на закрытом соединении или заданные параметры не являются ResultSet константами, указывающими тип и конкурентность; SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод или этот метод не поддерживается для указанного типа набора результатов и конкурентности набора результатов.
С:: 1.2

getTypeMap

Map<String,Class<?>> getTypeMap() throws SQLException

Возвращает объект Map, связанный с этим объектом Connection. Если приложение не добавило запись, возвращаемая карта типов будет пустой.

Необходимо вызвать setTypeMap после внесения изменений в объект Map, возвращаемый из getTypeMap, так как драйвер JDBC может создать внутреннюю копию объекта Map, переданного в setTypeMap:

      Map<String,Class<?>> myMap = con.getTypeMap();
      myMap.put("mySchemaName.ATHLETES", Athletes.class);
      con.setTypeMap(myMap);

Возвращает:

объект java.util.Map, связанный с этим объектом Connection

Выбрасывает:

SQLException - если происходит ошибка доступа к базе данных или этот метод вызывается на закрытом соединении

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.2

См. также:

setTypeMap

void setTypeMap(Map<String,Class<?>> map) throws SQLException

Устанавливает заданный объект TypeMap в качестве карты типов для этого объекта Connection. Карта типов будет использоваться для пользовательского отображения структурных типов SQL и типов-различий.

Необходимо задать значения для TypeMap перед вызовом setMap, так как драйвер JDBC может создать внутреннюю копию TypeMap:

      Map myMap<String,Class<?>> = new HashMap<String,Class<?>>();
      myMap.put("mySchemaName.ATHLETES", Athletes.class);
      con.setTypeMap(myMap);

Параметры:

map - объект java.util.Map, устанавливаемый в качестве замены для карты типов по умолчанию этого объекта Connection

Выбрасывает:

SQLException - если происходит ошибка доступа к базе данных, этот метод вызывается на закрытом соединении или заданный параметр не является объектом java.util.Map

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.2

См. также:

setHoldability

void setHoldability(int holdability) throws SQLException

Изменяет удерживаемость по умолчанию объектов ResultSet, созданных с помощью этого объекта Connection, на заданную удерживаемость. Удерживаемость по умолчанию объектов ResultSet можно определить, вызвав DatabaseMetaData.getResultSetHoldability().

Параметры:

holdability - константа удерживаемости ResultSet; одна из ResultSet.HOLD_CURSORS_OVER_COMMIT или ResultSet.CLOSE_CURSORS_AT_COMMIT

Выбрасывает:

SQLException - если происходит ошибка доступа к базе данных, этот метод вызывается на закрытом соединении или заданный параметр не является ResultSet константой, указывающей удерживаемость

SQLFeatureNotSupportedException - если заданная удерживаемость не поддерживается

С:

1.4

См. также:

getHoldability

int getHoldability() throws SQLException

Возвращает текущую удерживаемость объектов ResultSet, созданных с помощью этого объекта Connection.

Возвращает:

удерживаемость, одна из ResultSet.HOLD_CURSORS_OVER_COMMIT или ResultSet.CLOSE_CURSORS_AT_COMMIT

Выбрасывает:

SQLException - если происходит ошибка доступа к базе данных или этот метод вызывается на закрытом соединении

С:

1.4

См. также:

setSavepoint

Savepoint setSavepoint() throws SQLException

Создаёт безымянный сохраняемый момент в текущей транзакции и возвращает новый объект Savepoint, который его представляет.

если setSavepoint вызывается вне активной транзакции, транзакция будет начата в этом вновь созданном сохраняемом моменте.

Возвращает:

новый объект Savepoint

Выбрасывает:

SQLException - если происходит ошибка доступа к базе данных, этот метод вызывается при участии в распределённой транзакции, этот метод вызывается на закрытом соединении или этот объект Connection в настоящее время находится в режиме автоматического подтверждения

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

С:

1.4

См. также:

setSavepoint

Savepoint setSavepoint(String name) throws SQLException

Создаёт точку сохранения с заданным именем в текущей транзакции и возвращает новый Savepoint объект, представляющий её.

Если setSavepoint вызывается вне активной транзакции, будет начата транзакция в этой новой точке сохранения.

Parameters:

name - a String содержащий имя точки сохранения

Returns:

новый Savepoint объект

Throws:

SQLException - если произошла ошибка доступа к базе данных, этот метод вызывается во время участия в распределённой транзакции, этот метод вызывается для закрытого соединения или этот Connection объект в настоящее время в режиме автоматического подтверждения

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

Since:

1.4

See Also:

rollback

void rollback(Savepoint savepoint) throws SQLException

Отменяет все изменения, внесённые после того, как был установлен заданный Savepoint объект.

Этот метод следует использовать только когда отключено автоматическое подтверждение.

Parameters:

savepoint - объект Savepoint, до которого необходимо откатиться

Throws:

SQLException - если произошла ошибка доступа к базе данных, этот метод вызывается во время участия в распределённой транзакции, этот метод вызывается для закрытого соединения, объект Savepoint больше недействителен, или этот Connection объект в настоящее время в режиме автоматического подтверждения

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод

Since:

1.4

See Also:

releaseSavepoint

void releaseSavepoint(Savepoint savepoint) throws SQLException

Удаляет указанный Savepoint и последующие Savepoint объекты из текущей транзакции. Любая ссылка на точку сохранения после её удаления приведёт к выбрасыванию SQLException.

Parameters:: savepoint - объект Savepoint, который нужно удалить
Throws:: SQLException - если произошла ошибка доступа к базе данных, этот метод вызывается для закрытого соединения или указанный Savepoint объект не является действительной точкой сохранения в текущей транзакции; SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод
Since:: 1.4

createStatement

Statement createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException

Создаёт объект Statement, который будет генерировать ResultSet объекты с заданным типом, конкурентностью и возможностью удержания. Этот метод аналогичен методу createStatement выше, но позволяет переопределить значения по умолчанию для типа, конкурентности и возможности удержания набора результатов.

Parameters:

resultSetType - одно из следующих значений ResultSet: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE или ResultSet.TYPE_SCROLL_SENSITIVE

resultSetConcurrency - одно из следующих значений ResultSet: ResultSet.CONCUR_READ_ONLY или ResultSet.CONCUR_UPDATABLE

resultSetHoldability - одно из следующих значений ResultSet: ResultSet.HOLD_CURSORS_OVER_COMMIT или ResultSet.CLOSE_CURSORS_AT_COMMIT

Returns:

новый объект Statement, который будет генерировать ResultSet объекты с заданным типом, конкурентностью и возможностью удержания

Throws:

SQLException - если произошла ошибка доступа к базе данных, этот метод вызывается для закрытого соединения или заданные параметры не являются константами ResultSet, обозначающими тип, конкурентность и возможность удержания

SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод или метод не поддерживается для указанного типа набора результатов, возможности удержания набора результатов и конкурентности набора результатов.

Since:

1.4

See Also:

prepareStatement

PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException

Создаёт объект PreparedStatement, который будет генерировать ResultSet объекты с заданным типом, конкурентностью и возможностью удержания.

Этот метод аналогичен методу prepareStatement выше, но позволяет переопределить значения по умолчанию для типа, конкурентности и возможности удержания набора результатов.

Parameters:

sql - объект String, представляющий SQL-запрос, который будет отправлен в базу данных; может содержать один или несколько параметров '?' IN

resultSetType - одно из следующих значений ResultSet: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE или ResultSet.TYPE_SCROLL_SENSITIVE

resultSetConcurrency - одно из следующих значений ResultSet: ResultSet.CONCUR_READ_ONLY или ResultSet.CONCUR_UPDATABLE

resultSetHoldability - одно из следующих значений ResultSet: ResultSet.HOLD_CURSORS_OVER_COMMIT или ResultSet.CLOSE_CURSORS_AT_COMMIT

Returns:

новый объект PreparedStatement, содержащий предварительно скомпилированный SQL-запрос, который будет генерировать ResultSet объекты с заданным типом, конкурентностью и возможностью удержания

Throws:

Since:

1.4

See Also:

prepareCall

CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException

Создаёт объект CallableStatement, который будет генерировать ResultSet объекты с заданным типом и конкурентностью. Этот метод аналогичен методу prepareCall выше, но позволяет переопределить значения по умолчанию для типа, конкурентности и возможности удержания набора результатов.

Parameters:

sql - объект String, представляющий SQL-запрос, который будет отправлен в базу данных; может содержать один или несколько параметров '?'

resultSetType - одно из следующих значений ResultSet: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE или ResultSet.TYPE_SCROLL_SENSITIVE

resultSetConcurrency - одно из следующих значений ResultSet: ResultSet.CONCUR_READ_ONLY или ResultSet.CONCUR_UPDATABLE

resultSetHoldability - одно из следующих значений ResultSet: ResultSet.HOLD_CURSORS_OVER_COMMIT или ResultSet.CLOSE_CURSORS_AT_COMMIT

Returns:

новый объект CallableStatement, содержащий предварительно скомпилированный SQL-запрос, который будет генерировать ResultSet объекты с заданным типом, конкурентностью и возможностью удержания

Throws:

Since:

1.4

See Also:

prepareStatement

PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) throws SQLException

Создаёт стандартный объект PreparedStatement, который имеет возможность извлечения сгенерированных ключей. Заданная константа сообщает драйверу, нужно ли делать сгенерированные ключи доступными для извлечения. Этот параметр игнорируется, если SQL-запрос не является INSERT запросом или SQL-запросом, способным возвращать сгенерированные ключи (список таких запросов зависит от поставщика).

Примечание: Этот метод оптимизирован для работы с параметризованными SQL-запросами, которые получают выгоду от предварительной компиляции. Если драйвер поддерживает предварительную компиляцию, метод prepareStatement отправит запрос в базу данных для предварительной компиляции. Некоторые драйверы могут не поддерживать предварительную компиляцию. В этом случае запрос может не быть отправлен в базу данных до тех пор, пока объект PreparedStatement не будет выполнен. Это не оказывает прямого влияния на пользователей, но влияет на то, какие методы выбрасывают определённые исключения SQLException.

Наборы результатов, созданные с помощью возвращённого объекта PreparedStatement, по умолчанию будут иметь тип TYPE_FORWARD_ONLY и уровень конкурентности CONCUR_READ_ONLY. Возможность удержания созданных наборов результатов можно определить, вызвав getHoldability().

Parameters:: sql - SQL-запрос, который может содержать один или несколько заполнительных параметров '?' IN; autoGeneratedKeys - флаг, указывающий, нужно ли возвращать сгенерированные ключи; одно из значений Statement.RETURN_GENERATED_KEYS или Statement.NO_GENERATED_KEYS
Returns:: новый объект PreparedStatement, содержащий предварительно скомпилированный SQL-запрос, который будет иметь возможность возвращать сгенерированные ключи
Throws:: SQLException - если произошла ошибка доступа к базе данных, этот метод вызывается для закрытого соединения или заданный параметр не является константой Statement, указывающей, нужно ли возвращать сгенерированные ключи; SQLFeatureNotSupportedException - если драйвер JDBC не поддерживает этот метод с константой Statement.RETURN_GENERATED_KEYS
Since:: 1.4

prepareStatement

PreparedStatement prepareStatement(String sql, int[] columnIndexes) throws SQLException

Создаёт стандартный объект PreparedStatement, способный возвращать автоматически сгенерированные ключи, указанные заданным массивом. Этот массив содержит индексы столбцов в целевой таблице, которые содержат автоматически сгенерированные ключи, которые должны быть доступны. Драйвер проигнорирует массив, если SQL-запрос не является INSERT-запросом или SQL-запросом, способным возвращать автоматически сгенерированные ключи (список таких запросов зависит от поставщика).

SQL-запрос с параметрами IN или без них может быть предварительно скомпилирован и сохранён в объекте PreparedStatement. Этот объект затем может быть использован для эффективного многократного выполнения этого запроса.

Примечание: Этот метод оптимизирован для обработки параметрических SQL-запросов, которые выигрывают от предварительной компиляции. Если драйвер поддерживает предварительную компиляцию, метод prepareStatement отправит запрос в базу данных для предварительной компиляции. Некоторые драйверы могут не поддерживать предварительную компиляцию. В этом случае запрос может не быть отправлен в базу данных до выполнения объекта PreparedStatement. Это не оказывает прямого влияния на пользователей; однако это влияет на то, какие методы выбрасывают определённые исключения SQLException.

Результатные наборы, созданные с помощью возвращённого объекта PreparedStatement, по умолчанию будут иметь тип TYPE_FORWARD_ONLY и уровень одновременности CONCUR_READ_ONLY. Возможность удержания созданных наборов результатов можно определить, вызвав getHoldability().

Parameters:: sql - SQL-запрос, который может содержать один или несколько заменителей параметров IN «?»; columnIndexes - массив индексов столбцов, указывающий столбцы, которые должны быть возвращены из вставленной строки или строк
Returns:: новый объект PreparedStatement, содержащий предварительно скомпилированный запрос, способный возвращать автоматически сгенерированные ключи, указанные заданным массивом индексов столбцов
Throws:: SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении; SQLFeatureNotSupportedException - если JDBC-драйвер не поддерживает этот метод
Since:: 1.4

prepareStatement

PreparedStatement prepareStatement(String sql, String[] columnNames) throws SQLException

Создаёт стандартный объект PreparedStatement, способный возвращать автоматически сгенерированные ключи, указанные заданным массивом. Этот массив содержит имена столбцов в целевой таблице, которые содержат автоматически сгенерированные ключи, которые должны быть возвращены. Драйвер проигнорирует массив, если SQL-запрос не является INSERT-запросом или SQL-запросом, способным возвращать автоматически сгенерированные ключи (список таких запросов зависит от поставщика).

Parameters:: sql - SQL-запрос, который может содержать один или несколько заменителей параметров IN «?»; columnNames - массив имён столбцов, указывающий столбцы, которые должны быть возвращены из вставленной строки или строк
Returns:: новый объект PreparedStatement, содержащий предварительно скомпилированный запрос, способный возвращать автоматически сгенерированные ключи, указанные заданным массивом имён столбцов
Throws:: SQLException - если произошла ошибка доступа к базе данных или этот метод вызван на закрытом соединении; SQLFeatureNotSupportedException - если JDBC-драйвер не поддерживает этот метод
Since:: 1.4

createClob

Clob createClob() throws SQLException

Создаёт объект, реализующий интерфейс Clob. Возвращаемый объект изначально не содержит данных. Методы setAsciiStream, setCharacterStream и setString интерфейса Clob могут быть использованы для добавления данных в Clob.

Returns:: Объект, реализующий интерфейс Clob
Throws:: SQLException - если объект, реализующий интерфейс Clob, не может быть создан, этот метод вызывается на закрытом соединении или произошла ошибка доступа к базе данных.; SQLFeatureNotSupportedException - если JDBC-драйвер не поддерживает этот тип данных
Since:: 1.6

createBlob

Blob createBlob() throws SQLException

Создаёт объект, реализующий интерфейс Blob. Возвращаемый объект изначально не содержит данных. Методы setBinaryStream и setBytes интерфейса Blob могут быть использованы для добавления данных в Blob.

Returns:: Объект, реализующий интерфейс Blob
Throws:: SQLException - если объект, реализующий интерфейс Blob, не может быть создан, этот метод вызывается на закрытом соединении или произошла ошибка доступа к базе данных.; SQLFeatureNotSupportedException - если JDBC-драйвер не поддерживает этот тип данных
Since:: 1.6

createNClob

NClob createNClob() throws SQLException

Создаёт объект, реализующий интерфейс NClob. Возвращаемый объект изначально не содержит данных. Методы setAsciiStream, setCharacterStream и setString интерфейса NClob могут быть использованы для добавления данных в NClob.

Returns:: Объект, реализующий интерфейс NClob
Throws:: SQLException - если объект, реализующий интерфейс NClob, не может быть создан, этот метод вызывается на закрытом соединении или произошла ошибка доступа к базе данных.; SQLFeatureNotSupportedException - если JDBC-драйвер не поддерживает этот тип данных
Since:: 1.6

createSQLXML

SQLXML createSQLXML() throws SQLException

Создаёт объект, реализующий интерфейс SQLXML. Возвращаемый объект изначально не содержит данных. Объект createXmlStreamWriter и метод setString интерфейса SQLXML могут быть использованы для добавления данных в объект SQLXML.

Returns:: Объект, реализующий интерфейс SQLXML
Throws:: SQLException - если объект, реализующий интерфейс SQLXML, не может быть создан, этот метод вызывается на закрытом соединении или произошла ошибка доступа к базе данных.; SQLFeatureNotSupportedException - если JDBC-драйвер не поддерживает этот тип данных
Since:: 1.6

isValid

boolean isValid(int timeout) throws SQLException

Возвращает true, если соединение не закрыто и всё ещё валидно. Драйвер должен отправить запрос к соединению или использовать другой механизм, который положительно подтвердит, что соединение всё ещё валидно, когда этот метод вызывается.

Запрос, отправленный драйвером для проверки соединения, будет выполнен в контексте текущей транзакции.

Parameters:

timeout - Время в секундах ожидания завершения операции базы данных, используемой для проверки соединения. Если таймаут истечёт до завершения операции, этот метод вернёт false. Значение 0 указывает, что таймаут к операции базы данных не применяется.

Returns:

true, если соединение валидно, false в противном случае

Throws:

SQLException - если значение, предоставленное для timeout, меньше 0

Since:

1.6

See Also:

setClientInfo

void setClientInfo(String name, String value) throws SQLClientInfoException

Устанавливает значение свойства client info, заданного именем, в значение, указанное значением.

Приложения могут использовать метод DatabaseMetaData.getClientInfoProperties для определения свойств client info, поддерживаемых драйвером, и максимальной длины, которая может быть указана для каждого свойства.

Драйвер сохраняет указанное значение в подходящем месте в базе данных. Например, в специальном регистре, параметре сессии или столбце системной таблицы. Для повышения эффективности драйвер может отложить установку значения в базе данных до следующего выполнения или подготовки оператора. Помимо хранения информации о клиенте в соответствующем месте в базе данных, эти методы не должны каким-либо образом изменять поведение соединения. Указанные значения используются только для целей учета, диагностики и отладки.

Драйвер должен сгенерировать предупреждение, если указанное имя свойства client info не распознается драйвером.

Если значение, указанное в этом методе, превышает максимальную длину для свойства, драйвер может либо обрезать значение и сгенерировать предупреждение, либо сгенерировать SQLClientInfoException. Если драйвер генерирует SQLClientInfoException, указанное значение не было установлено в соединении.

Ниже приведены стандартные свойства client info. Драйверы не обязаны поддерживать эти свойства, однако, если драйвер поддерживает свойство client info, которое можно описать одним из стандартных свойств, должно использоваться стандартное имя свойства.

ApplicationName - Имя приложения, в настоящее время использующего соединение
ClientUser - Имя пользователя, от имени которого приложение, использующее соединение, выполняет работу. Это может не совпадать с именем пользователя, которое использовалось при установлении соединения.
ClientHostname - Имя хоста компьютера, на котором выполняется приложение, использующее соединение.

Parameters:: name - Имя свойства client info для установки; value - Значение для установки свойства client info. Если значение равно null, текущее значение указанного свойства сбрасывается.
Throws:: SQLClientInfoException - если сервер базы данных возвращает ошибку при установке значения client info на сервере базы данных или этот метод вызывается для закрытого соединения
Since:: 1.6

setClientInfo

void setClientInfo(Properties properties) throws SQLClientInfoException

Устанавливает значения свойств client info соединения. Объект Properties содержит имена и значения свойств client info, которые должны быть установлены. Набор свойств client info, содержащихся в списке свойств, заменяет текущий набор свойств client info в соединении. Если свойство, которое в настоящее время установлено в соединении, отсутствует в списке свойств, это свойство сбрасывается. Указание пустого списка свойств приведет к сбросу всех свойств в соединении. Дополнительную информацию см. в setClientInfo (String, String).

Если при установке любого из свойств client info произойдет ошибка, будет выброшено исключение SQLClientInfoException. Объект SQLClientInfoException содержит информацию, указывающую, какие свойства client info не были установлены. Состояние информации о клиенте неизвестно, поскольку некоторые базы данных не позволяют устанавливать несколько свойств client info атомарно. Для таких баз данных одно или несколько свойств могут быть установлены до возникновения ошибки.

Parameters:

properties - список свойств client info для установки

Throws:

SQLClientInfoException - если сервер базы данных возвращает ошибку при установке значений clientInfo на сервере базы данных или этот метод вызывается для закрытого соединения

Since:

1.6

See Also:

getClientInfo

String getClientInfo(String name) throws SQLException

Возвращает значение свойства client info, заданного именем. Этот метод может возвращать null, если указанное свойство client info не было установлено и не имеет значения по умолчанию. Этот метод также вернет null, если указанное имя свойства client info не поддерживается драйвером.

Приложения могут использовать метод DatabaseMetaData.getClientInfoProperties для определения свойств client info, поддерживаемых драйвером.

Parameters:

name - Имя свойства client info для извлечения

Returns:

Значение свойства client info

Throws:

SQLException - если сервер базы данных возвращает ошибку при получении значения client info из базы данных или этот метод вызывается для закрытого соединения

Since:

1.6

See Also:

getClientInfo

Properties getClientInfo() throws SQLException

Возвращает список, содержащий имя и текущее значение каждого свойства client info, поддерживаемого драйвером. Значение свойства client info может быть null, если свойство не было установлено и не имеет значения по умолчанию.

Returns:: Объект Properties, содержащий имя и текущее значение каждого из свойств client info, поддерживаемых драйвером.
Throws:: SQLException - если сервер базы данных возвращает ошибку при получении значений client info из базы данных или этот метод вызывается для закрытого соединения
Since:: 1.6

createArrayOf

Array createArrayOf(String typeName, Object[] elements) throws SQLException

Метод-фабрика для создания объектов Array.

Примечание: Когда createArrayOf используется для создания объекта массива, который отображается на примитивный тип данных, то определяется, является ли объект Array массивом этого примитивного типа данных или массивом Object.

Примечание: Драйвер JDBC отвечает за отображение элементов Object массива в стандартный JDBC SQL-тип, определенный в java.sql.Types для данного класса Object. Стандартное отображение указано в приложении B спецификации JDBC. Если полученный JDBC-тип не является подходящим типом для данного typeName, то определяется, будет ли выброшено исключение SQLException или драйвер поддерживает преобразование.

Parameters:: typeName - SQL-имя типа, к которому отображаются элементы массива. typeName — имя, специфичное для базы данных, которое может быть именем встроенного типа, пользовательского типа или стандартного SQL-типа, поддерживаемого этой базой данных. Это значение, возвращаемое Array.getBaseTypeName; elements - элементы, заполняющие возвращаемый объект
Returns:: объект Array, элементы которого отображаются на указанный SQL-тип
Throws:: SQLException - если возникает ошибка базы данных, JDBC-тип не подходит для typeName и преобразование не поддерживается, typeName равен null или этот метод вызывается для закрытого соединения; SQLFeatureNotSupportedException - если JDBC-драйвер не поддерживает этот тип данных
Since:: 1.6

createStruct

Struct createStruct(String typeName, Object[] attributes) throws SQLException

Метод-фабрика для создания объектов Struct.

Parameters:: typeName - SQL-имя типа SQL-структурированного типа, к которому отображается этот объект Struct. typeName — имя пользовательского типа, определенного для этой базы данных. Это значение, возвращаемое Struct.getSQLTypeName.; attributes - атрибуты, заполняющие возвращаемый объект
Returns:: объект Struct, отображаемый на указанный SQL-тип и заполненный указанными атрибутами
Throws:: SQLException - если возникает ошибка базы данных, typeName равен null или этот метод вызывается для закрытого соединения; SQLFeatureNotSupportedException - если JDBC-драйвер не поддерживает этот тип данных
Since:: 1.6

setSchema

void setSchema(String schema) throws SQLException

Устанавливает имя схемы для доступа.

Если драйвер не поддерживает схемы, он проигнорирует этот запрос.

Вызов setSchema не влияет на ранее созданные или подготовленные объекты Statement. Определяется, выполняется ли операция prepare DBMS немедленно при вызове методов Connection, prepareStatement или prepareCall. Для максимальной переносимости setSchema следует вызывать перед созданием или подготовкой Statement.

Parameters:

schema - имя схемы, в которой необходимо работать

Throws:

SQLException - если возникает ошибка доступа к базе данных или этот метод вызывается для закрытого соединения

Since:

1.7

See Also:

getSchema

String getSchema() throws SQLException

Возвращает текущее имя схемы этого объекта Connection.

Returns:

текущее имя схемы или null, если его нет

Throws:

SQLException - если возникает ошибка доступа к базе данных или этот метод вызывается для закрытого соединения

Since:

1.7

See Also:

прервать

void abort(Executor executor) throws SQLException

Прерывает открытое соединение. Вызов abort приводит к:

Соединение помечается как закрытое
Закрытие любого физического соединения с базой данных
Освобождение ресурсов, используемых соединением
Гарантирует, что любой поток, в данный момент работающий с соединением, либо завершит работу, либо выбросит исключение SQLException.

Вызов abort помечает соединение как закрытое и освобождает любые ресурсы. Вызов abort для закрытого соединения — это операция без действия.

Возможны задержки при прерывании и освобождении ресурсов, удерживаемых соединением. После возврата метода abort соединение будет помечено как закрытое, а поток Executor, переданный в качестве параметра методу abort, может всё ещё выполнять задачи по освобождению ресурсов.

Параметры:

executor — реализация интерфейса Executor, которая будет использоваться методом abort.

Исключения:

SQLException — если произошла ошибка доступа к базе данных или реализация интерфейса executor находится в состоянии null

С:

1.7

См. также:

установитьТаймаутСети

void setNetworkTimeout(Executor executor, int milliseconds) throws SQLException

Устанавливает максимальный период ожидания ответа базы данных от любого запроса Connection или объектов, созданных на основе Connection. Если запрос остаётся без ответа, метод ожидания вернёт исключение SQLException, а Connection или объекты, созданные на основе Connection, будут помечены как закрытые. Любое последующее использование объектов, за исключением методов close, isClosed или Connection.isValid, приведёт к исключению SQLException.

Примечание: Этот метод предназначен для решения редкой, но серьёзной проблемы, когда разрывы сети могут привести к зависанию потоков, отправляющих вызовы JDBC в чтении сокетов, до тех пор, пока не истечёт TCP-TIMEOUT операционной системы (обычно 10 минут). Этот метод связан с методом abort() , который предоставляет административному потоку возможность освободить такие потоки в случаях, когда соединение JDBC доступно административному потоку. Метод setNetworkTimeout будет обрабатывать случаи, когда нет административного потока или он не имеет доступа к соединению. Этот метод имеет серьёзные последствия и должен быть задан достаточно большим значением, чтобы никогда не срабатывать раньше других таймаутов, таких как таймауты транзакций.

Реализации драйверов JDBC также могут выбрать поддержку метода setNetworkTimeout для установления ограничения на время ответа базы данных в средах без сети.

Драйверы могут реализовывать некоторые или все свои вызовы API с несколькими внутренними передачами драйвер-база данных, и реализация драйвера определяет, будет ли ограничение всегда применяться к ответу на вызов API или к каждому отдельному запросу, сделанному во время вызова API.

Этот метод можно вызывать более одного раза, например, для установки ограничения для участка кода JDBC и сброса до значения по умолчанию при выходе из этого участка. Вызов этого метода не влияет на уже ожидающие запросы.

Таймаут сети Statement.setQueryTimeout() независим от таймаута, заданного в setNetworkTimeout. Если таймаут запроса истечёт раньше таймаута сети, выполнение запроса будет отменено. Если сеть всё ещё активна, результат будет таким, что и запрос, и соединение останутся пригодными для использования. Однако если таймаут сети истечёт раньше таймаута запроса или если таймаут запроса завершится неудачей из-за проблем с сетью, соединение будет помечено как закрытое, все ресурсы, удерживаемые соединением, будут освобождены, и соединение и запрос будут непригодны для использования.

Когда драйвер определит, что таймаут setNetworkTimeout истек, драйвер JDBC помечает соединение как закрытое и освобождает любые ресурсы, удерживаемые соединением.

Параметры:

executor — реализация интерфейса Executor, которая будет использоваться методом setNetworkTimeout.

milliseconds — время в миллисекундах, которое драйвер будет ждать завершения операции базы данных. Если драйвер JDBC не поддерживает миллисекунды, драйвер JDBC округлится до ближайшей секунды. Если период таймаута истечёт до завершения операции, будет брошено исключение SQLException. Значение 0 указывает, что нет таймаута для операций базы данных.

Исключения:

SQLException — если произошла ошибка доступа к базе данных, метод вызывается для закрытого соединения, реализация интерфейса executor находится в состоянии null или значение, указанное для seconds, меньше 0.

SQLFeatureNotSupportedException — если драйвер JDBC не поддерживает этот метод

С:

1.7

См. также:

получитьТаймаутСети

int getNetworkTimeout() throws SQLException

Возвращает количество миллисекунд, которое драйвер будет ждать завершения запроса к базе данных. Если ограничение превышено, будет брошено исключение SQLException.

Возвращает:

текущее ограничение таймаута в миллисекундах; ноль означает отсутствие ограничения

Исключения:

SQLException — если произошла ошибка доступа к базе данных или этот метод вызывается для закрытого Connection

SQLFeatureNotSupportedException — если драйвер JDBC не поддерживает этот метод

С:

1.7

См. также:

beginRequest

default void beginRequest() throws SQLException

Указывает драйверу, что начинается запрос, независимая единица работы, для этого соединения. Каждый запрос независим от других запросов относительно состояния, локального для соединения, как на клиенте, так и на сервере. Работа, выполняемая между парами beginRequest, endRequest, не зависит от любой другой работы, выполненной на соединении, будь то часть другого запроса или вне любого запроса. Запрос может включать несколько транзакций. Может быть зависимость от состояния базы данных, которое было сохранено, так как это не локально для соединения.

Локальное состояние определяется как любое состояние, связанное с соединением, которое является локальным для текущего соединения, как на клиенте, так и в базе данных, которое не может быть прозрачно воспроизведено.

Вызовы beginRequest и endRequest не вложены. Многократные вызовы beginRequest без промежуточного вызова endRequest не являются ошибкой. Первый вызов beginRequest отмечает начало запроса, и последующие вызовы обрабатываются как операция без действия.

Использование методов beginRequest и endRequest является необязательным, зависит от поставщика и должно быть в основном прозрачным. В частности, реализации могут обнаруживать условия, указывающие на зависимость от другой работы, например, открытой транзакции. Рекомендуется, хотя и не обязательно, чтобы реализации выбрасывали исключение SQLException, если существует активная транзакция, и вызывается beginRequest. Использование этих методов может повысить производительность или обеспечить другие преимущества. Обратитесь к документации поставщика для получения дополнительной информации.

Рекомендуется заключать каждый блок работы в пары beginRequest, endRequest таким образом, чтобы в начале или конце запроса не было открытой транзакции и не было зависимости от локального состояния, пересекающего границы запросов. Сохранённое состояние базы данных не является локальным.

Примечание API:

Этот метод предназначен для использования менеджерами пулов соединений.

Менеджер пула должен вызвать метод beginRequest для базового соединения перед возвращением соединения вызывающему объекту.

Менеджеру пула не нужно вызывать beginRequest, если:

Пул соединений кэширует объекты PooledConnection
Возвращает логическую ручку соединения, когда getConnection вызывается приложением
Логическое соединение Connection закрывается вызовом Connection.close перед возвращением PooledConnection в кэш.

Требования к реализации:

Реализация по умолчанию — это операция без действия.

Исключения:

SQLException — если произошла ошибка

С:

См. также:

endRequest

default void endRequest() throws SQLException

Уведомление драйверу о завершении запроса, независимой единицы работы. Вызовы beginRequest и endRequest не являются вложенными. Несколько вызовов endRequest без промежуточного вызова beginRequest не является ошибкой. Первый вызов endRequest отмечает завершение запроса, последующие вызовы обрабатываются как бесполезные операции. Если вызов endRequest осуществляется без предварительного вызова beginRequest, он считается бесполезной операцией.

Точное поведение этого метода зависит от поставщика. В частности, реализации могут обнаруживать условия, указывающие на зависимость от другой работы, такой как открытая транзакция. Рекомендуется, хотя и не обязательно, чтобы реализации выбрасывали исключение SQLException, если активна транзакция, и вызывается endRequest.

Примечание API:

Этот метод предназначен для использования менеджерами пулов соединений.

Менеджер пула должен вызывать endRequest для базового соединения, когда приложение возвращает соединение обратно в пул соединений.

Менеджеру пула нет необходимости вызывать endRequest в следующих случаях:

Пул соединений кэширует объекты PooledConnection
Возвращает логическую ручку соединения при вызове getConnection приложением
Логическое Connection закрывается путем вызова Connection.close перед возвращением PooledConnection в кэш.

Требования к реализации:

Реализация по умолчанию - это бесполезная операция.

Исключения:

SQLException - если произошла ошибка

С:

См. также:

setShardingKeyIfValid

default boolean setShardingKeyIfValid(ShardingKey shardingKey, ShardingKey superShardingKey, int timeout) throws SQLException

Устанавливает и проверяет фрагментирующие ключи для этого соединения. Для фрагментирующего ключа может быть указано значение null. Действительность фрагментирующего ключа null зависит от поставщика. Обратитесь к документации поставщика для получения дополнительной информации.

Примечание API:

Этот метод проверяет, что фрагментирующие ключи действительны для Connection. Значение тайм-аута указывает, как долго драйвер должен ждать, пока Connection проверит, действителен ли фрагментирующий ключ, прежде чем setShardingKeyIfValid вернёт false.

Требования к реализации:

Реализация по умолчанию выбросит исключение SQLFeatureNotSupportedException.

Параметры:

shardingKey - фрагментирующий ключ, который будет проверен по отношению к этому соединению. Фрагментирующий ключ может быть null

superShardingKey - суперфрагментирующий ключ, который будет проверен по отношению к этому соединению. Суперфрагментирующий ключ может быть null.

timeout - время в секундах, по истечении которого ожидается завершение процесса проверки, в противном случае процесс проверки прерывается. Значение 0 означает, что процесс проверки не будет ограничен по времени.

Возвращает:

true, если соединение и фрагментирующие ключи действительны и установлены для этого соединения; false, если фрагментирующие ключи недействительны или период тайм-аута истекает до завершения операции.

Исключения:

SQLException - если при выполнении этой проверки произошла ошибка; superShardingKey указан без shardingKey; этот метод вызван для закрытого connection; или значение timeout отрицательное.

SQLFeatureNotSupportedException - если драйвер не поддерживает фрагментацию

С:

См. также:

setShardingKeyIfValid

default boolean setShardingKeyIfValid(ShardingKey shardingKey, int timeout) throws SQLException

Устанавливает и проверяет фрагментирующий ключ для этого соединения. Для фрагментирующего ключа может быть указано значение null. Действительность фрагментирующего ключа null зависит от поставщика. Обратитесь к документации поставщика для получения дополнительной информации.

Примечание API:

Этот метод проверяет, что фрагментирующий ключ действителен для Connection. Значение тайм-аута указывает, как долго драйвер должен ждать, пока Connection проверит, действителен ли фрагментирующий ключ, прежде чем setShardingKeyIfValid вернёт false.

Требования к реализации:

Реализация по умолчанию выбросит исключение SQLFeatureNotSupportedException.

Параметры:

Возвращает:

true, если соединение и фрагментирующий ключ действительны и установлены для этого соединения; false, если фрагментирующий ключ недействителен или период тайм-аута истекает до завершения операции.

Исключения:

SQLException - если при выполнении этой проверки произошла ошибка; этот метод вызван для закрытого connection; или значение timeout отрицательное.

SQLFeatureNotSupportedException - если драйвер не поддерживает фрагментацию

С:

См. также:

setShardingKey

default void setShardingKey(ShardingKey shardingKey, ShardingKey superShardingKey) throws SQLException

Указывает фрагментирующий ключ и суперфрагментирующий ключ для использования с этим соединением

Примечание API:

Этот метод устанавливает указанные фрагментирующие ключи, но не требует обратного запроса в базу данных для проверки того, что фрагментирующие ключи действительны для Connection.

Требования к реализации:

Реализация по умолчанию выбросит исключение SQLFeatureNotSupportedException.

Параметры:

shardingKey - фрагментирующий ключ, который необходимо установить для этого соединения. Фрагментирующий ключ может быть null

superShardingKey - суперфрагментирующий ключ, который необходимо установить для этого соединения. Суперфрагментирующий ключ может быть null

Исключения:

SQLException - если при установке фрагментирующих ключей произошла ошибка; этот метод вызван для закрытого connection; или superShardingKey указан без shardingKey

SQLFeatureNotSupportedException - если драйвер не поддерживает фрагментацию

С:

См. также:

setShardingKey

default void setShardingKey(ShardingKey shardingKey) throws SQLException

Указывает фрагментирующий ключ для использования с этим соединением

Примечание API:

Этот метод устанавливает указанный фрагментирующий ключ, но не требует обратного запроса в базу данных для проверки того, что фрагментирующий ключ действителен для Connection.

Требования к реализации:

Реализация по умолчанию выбросит исключение SQLFeatureNotSupportedException.

Параметры:

Исключения:

SQLException - если при установке фрагментирующего ключа произошла ошибка; или этот метод вызван для закрытого connection

SQLFeatureNotSupportedException - если драйвер не поддерживает фрагментацию

С:

См. также:

© 1993, 2025, 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://download.java.net/java/early_access/jdk24/docs/api/java.sql/java/sql/Connection.html