Глава 4. Установка Connector/J

Можно установить пакет Connector/J, используя дистрибутив исполняемых модулей или исходный код. В то время как двоичный дистрибутив предоставляет самый легкий метод для установки, исходный текст позволяет вам настроить свою установку. Оба типа пакетов доступны с Connector/J Download page. Исходный текст Connector/J также доступен на GitHub в https://github.com/mysql/mysql-connector-j.

Connector/J также доступен как Maven artifact в Central Repository. См. раздел 4.2.

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

Вы, возможно, также должны установить следующие сторонние библиотеки в своей системе для Connector/J 8.0:

Эти и другие сторонние библиотеки требуются для сборки Connector/J из исходных текстов (см. раздел для получения дополнительной информации о необходимых библиотеках).

4.1. Установка Connector/J из двочиного дистрибутива

Получение и использование пакетов

Различные типы двоичных пакетов для Connector/J доступны на Connector/J Download page. Следующее объясняет, как использовать каждый тип пакетов, чтобы установить Connector/J.

Используя независимые от платформы архивы: .tar.gz или .zip доступны для установки Connector/J на любой платформе. Используя соответствующую графическую утилиту или командной строки (например, tar для .tar.gz и WinZip для .zip), извлеките архив JAR из .tar.gz или .zip.

Поскольку есть потенциально длинные имена файлов, архивы Connector/J используют формат архива GNU Tar. Используйте GNU Tar или совместимое приложение, чтобы распаковать .tar.gz.

Используя пакеты для систем управления пакетами программного обеспечения на платформах Linux: RPM и Debian доступны для установки Connector/J в ряде дистрибутивов Linux, таких как Oracle Linux, Debian, Ubuntu, SUSE и так далее. Установите эти пакеты, используя систему управления пакетами программного обеспечения вашей системы.

Настройка CLASSPATH

Когда mysql-connector-java- version.jar был извлечен из двоичного пакета, закончите установку драйвера, разместив архив JAR в вашем Java classpath, добавив его полный путь к файлу к вашей переменной окружения CLASSPATH или непосредственно определяя путь к файлу опцией командной строки -cp, запуская JVM.

Например, на платформах Linux, добавьте драйвер Connector/J к вашей CLASSPATH с использованием одной из следующих форм, в зависимости от командного процессора:

# Bourne-compatible shell (sh, ksh, bash, zsh):
shell> export CLASSPATH=/path/mysql-connector-java-ver.jar:$CLASSPATH
# C shell (csh, tcsh):
shell> setenv CLASSPATH /path/mysql-connector-java-ver.jar:$CLASSPATH

Можно также установить CLASSPATH в файле профиля, любой в местном масштабе для пользователя в файле .profile, .login или другом файле входа в систему, или глобально, редактируя файл /etc/profile.

Для Windows вы устанавливаете переменную окружения через System Control Panel.

Не забудьте также добавить местоположения сторонних библиотек, требуемых для использования Connector/J в CLASSPATH.

Настройка Connector/J для серверов приложений

Чтобы использовать MySQL Connector/J с сервером приложений, таким как GlassFish, Tomcat или JBoss, изучите документацию вашего поставщика для получения информации о том, как формировать сторонние библиотеки классов, поскольку большинство серверов приложений игнорирует переменную CLASSPATH. Для примеров конфигурации некоторых серверов приложений J2EE см. главу 8, разделы 9.3 и 9.5. Однако авторитетный источник для конфигурационной информации пула связи JDBC это документация для вашего собственного сервера приложений.

Если вы разрабатываете сервлеты или JSP, и ваш сервер приложений J2EE-совместим, можно поместить файл .jar драйвера в подкаталог WEB-INF/lib вашего веб-приложения, поскольку это стандартное место для сторонних библиотек классов в веб-приложениях J2EE. Можно также использовать классы MysqlDataSource или MysqlConnectionPoolDataSource пакета the com.mysql.cj.jdbc, если ваш сервер приложений J2EE поддерживает или требует их. Интерфейс javax.sql.XADataSource осуществляется, используя класс com.mysql.cj.jdbc.MysqlXADataSource, который поддерживает распределенные транзакции XA. Различные классы MysqlDataSource поддерживают следующие параметры (через мутаторы стандартного набора):

4.2. Установка Connector/J через Maven

Можно также использовать менеджер зависимостей Maven, чтобы установить и формировать библиотеку Connector/J в проекте. Connector/J есть в Maven Central Repository с "GroupId: mysql" и "ArtifactId: mysql-connector-java" и может быть связан с вашим проектом, включив следующую зависимость в файле pom.xml:

<dependency>
  <groupId>mysql</groupId>
  <artifactId>mysql-connector-java</artifactId>
  <version>x.y.z</version>
</dependency>

Обратите внимание на то, что, если вы используете Maven, чтобы управлять вашими зависимостями проекта, вы не должны явно обращаться к библиотеке protobuf-java поскольку это решено транзитивностью зависимости. Однако, если вы не хотите использовать функции X DevAPI, можно также хотеть добавить исключение зависимости, чтобы избежать связывать ненужную подбиблиотеку. Например:

<dependency>
  <groupId>mysql</groupId>
  <artifactId>mysql-connector-java</artifactId>
  <version>x.y.z</version>
  <exclusions>
    <exclusion>
      <groupId>com.google.protobuf</groupId>
      <artifactId>protobuf-java</artifactId>
    </exclusion>
  </exclusions>
</dependency>

4.3. Установка из исходных текстов

Прочитайте эту секцию, только если вы хотите построить настроенную версию Connector/J из исходных текстов или если вы интересуетесь помощью нам, чтобы проверить наш новый код. Чтобы просто получить MySQL Connector/J и работать с ним на вашей системе, установите Connector/J с использованием стандартного двоичного дистрибутива, см раздел 4.1.

Чтобы установить MySQL Connector/J из исходных текстов удостоверьтесь, что у вас есть следующее программное обеспечение на вашей системе:

Чтобы построить MySQL Connector/J из исходных текстов выполните эти шаги:

  1. Удостоверьтесь, что у вас есть установленный JDK 1.8.x.

  2. Получите исходные тексты Connector/J одним из следующих средств:

  3. Разместите все необходимые сторонние библиотеки в отдельном каталоге, например, /home/username/ant-extralibs.

  4. Измените свой текущий рабочий каталог на созданный на втором шаге каталог mysql-connector-j.

  5. Создайте файл build.properties, чтобы указать Ant на местоположения корневых каталогов для вашего JDK 1.8.x, а также дополнительных библиотек. Файл должен содержать следующие параметры настройки, части path_to_* заменяются соответствующими путями к файлам:

    com.mysql.cj.build.jdk=path_to_jdk_1.8
    com.mysql.cj.extra.libs=path_to_folder_for_extra_libraries
    

    Альтернативно, можно установить значения тех свойств через опции -D в Ant.

    Переходя от Connector/J 5.1 до 8.0, много свойств Ant для сборки Connector/J были переименованы или удалены, посмотрите раздел 4.4.1.4 .

  6. Дайте следующую команду, чтобы собрать драйвер и создать файл .jar для Connector/J:

    shell> ant dist
    

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

    Для получения информации обо всех целях сборки, включая те, которые создают полностью упакованный дистрибутив, дайте следующую команду:

    shell> ant -projecthelp
    
  7. Установите недавно созданный файл .jar для драйвера JDBC как вы установили бы скачанный файл .jar, следуя инструкциям, данным здесь или здесь.

4.4. Модернизация от более старой версии

В этой секции есть информация для пользователей, которые переходят от одной версии Connector/J к другой, или к новой версии сервера MySQL, который поддерживает более свежий уровень JDBC. Более новая версия Connector/J может включать изменения, чтобы поддерживать новые функции, улучшить существующую функциональность или выполнить новые стандарты.

4.4.1. Модернизация до MySQL Connector/J 8.0

Модернизация приложения, разработанного для Connector/J 5.1, чтобы использовать Connector/J 8.0, могла бы потребовать определенных изменений вашего кода или окружающей среды, в которой это работает. Вот некоторые изменения для Connector/J от 5.1 до 8.0, для которых могли бы требоваться ваши усилия:

4.4.1.1. Запуск на Java 8

Connector/J 8.0 создается, чтобы работать с Java 8. В то время как Java 8 совместима с более ранними версиями Java, несовместимости действительно существуют, и код, разработанный, чтобы работать с Java 7, возможно, должен был бы быть приспособлен прежде, чем выполнять его Java 8. Разработчики должны обратиться к incompatibility information от Oracle.

4.4.1.2. Изменения в свойствах связи

Полный список свойств связи Connector/J 8.0 доступен в connector-j-reference-set-config. Следующее это свойства связи, которые были изменены при переходе Connector/J от 5.1 к 8.0.

Свойства, которые были удалены:

Свойства, которые были добавлены:

Сптсок переименованных свойств:

Свойства, которым изменили значения по умолчанию:

4.4.1.3. Изменения в Connector/J API

Эта секция описывает некоторые более важные изменения в Connector/J API при переходе с 5.1 на 8.0. Вы, возможно, должны были бы приспособить свои вызовы API соответственно:

4.4.1.4. Изменения для свойств сборки

Много свойств Ant для сборки Connector/J из исходных текстов были переименованы, см. таблицу 4.1.

Таблица 4.1. Изменения свойств сборки Connector/J с 5.1 на 8.0

Старое имяНовое имя
com.mysql.jdbc.extra.libs com.mysql.cj.extra.libs
com.mysql.jdbc.jdk com.mysql.cj.build.jdk
debug.enable com.mysql.cj.build.addDebugInfo
com.mysql.jdbc.noCleanBetweenCompiles com.mysql.cj.build.noCleanBetweenCompiles
com.mysql.jdbc.commercialBuild com.mysql.cj.build.commercial
com.mysql.jdbc.filterLicense com.mysql.cj.build.filterLicense
com.mysql.jdbc.noCryptoBuild com.mysql.cj.build.noCrypto
com.mysql.jdbc.noSources com.mysql.cj.build.noSources
com.mysql.jdbc.noMavenSources com.mysql.cj.build.noMavenSources
major_version com.mysql.cj.build.driver.version.major
minor_version com.mysql.cj.build.driver.version.minor
subminor_version com.mysql.cj.build.driver.version.subminor
version_status com.mysql.cj.build.driver.version.status
extra.version com.mysql.cj.build.driver.version.extra
snapshot.version com.mysql.cj.build.driver.version.snapshot
version com.mysql.cj.build.driver.version
full.version com.mysql.cj.build.driver.version.full
prodDisplayName com.mysql.cj.build.driver.displayName
prodName com.mysql.cj.build.driver.name
fullProdName com.mysql.cj.build.driver.fullName
buildDir com.mysql.cj.build.dir
buildDriverDir com.mysql.cj.build.dir.driver
mavenUploadDir com.mysql.cj.build.dir.maven
distDir com.mysql.cj.dist.dir
toPackage com.mysql.cj.dist.dir.prepare
packageDest com.mysql.cj.dist.dir.package
com.mysql.jdbc.docs.sourceDir com.mysql.cj.dist.dir.prebuilt.docs

4.4.1.5. Изменения тестовых свойств

Много свойств Ant для тестирования Connector/J были переименованы или удалены, см. таблицу 4.2.

Таблица 4.2. Изменения тестовых свойств Connector/J с 5.1 на 8.0

Старое имяНовое имя
buildTestDir com.mysql.cj.testsuite.build.dir
junit.results com.mysql.cj.testsuite.junit.results
com.mysql.jdbc.testsuite.jvm com.mysql.cj.testsuite.jvm
test com.mysql.cj.testsuite.test.class
methods com.mysql.cj.testsuite.test.methods
com.mysql.jdbc.testsuite.url com.mysql.cj.testsuite.url
com.mysql.jdbc.testsuite.admin-url com.mysql.cj.testsuite.url.admin
com.mysql.jdbc.testsuite.ClusterUrl com.mysql.cj.testsuite.url.cluster
com.mysql.jdbc.testsuite.url.sha256default com.mysql.cj.testsuite.url.openssl
com.mysql.jdbc.testsuite.cantGrant com.mysql.cj.testsuite.cantGrant
com.mysql.jdbc.testsuite.no-multi-hosts-tests com.mysql.cj.testsuite.disable.multihost.tests
com.mysql.jdbc.test.ds.host com.mysql.cj.testsuite.ds.host
com.mysql.jdbc.test.ds.port com.mysql.cj.testsuite.ds.port
com.mysql.jdbc.test.ds.db com.mysql.cj.testsuite.ds.db
com.mysql.jdbc.test.ds.user com.mysql.cj.testsuite.ds.user
com.mysql.jdbc.test.ds.password com.mysql.cj.testsuite.ds.password
com.mysql.jdbc.test.tabletype com.mysql.cj.testsuite.loadstoreperf.tabletype
com.mysql.jdbc.testsuite.loadstoreperf.useBigResults com.mysql.cj.testsuite.loadstoreperf.useBigResults
com.mysql.jdbc.testsuite.MiniAdminTest.runShutdown com.mysql.cj.testsuite.miniAdminTest.runShutdown
com.mysql.jdbc.testsuite.noDebugOutput com.mysql.cj.testsuite.noDebugOutput
com.mysql.jdbc.testsuite.retainArtifacts com.mysql.cj.testsuite.retainArtifacts
com.mysql.jdbc.testsuite.runLongTests com.mysql.cj.testsuite.runLongTests
com.mysql.jdbc.test.ServerController.basedir com.mysql.cj.testsuite.serverController.basedir
com.mysql.jdbc.ReplicationConnection.isSlave com.mysql.cj.testsuite.replicationConnection.isSlave
com.mysql.jdbc.test.isLocalHostnameReplacement Удалено
com.mysql.jdbc.testsuite.driver Удалено
com.mysql.jdbc.testsuite.url.default Удалено. Больше не надо: тесты multi-JVM были удалены из набора тестов.

4.4.1.6. Изменения для исключений

Некоторые исключения были удалены из Connector/J при переходе от 5.1 к 8.0. Приложения, которые раньше ловили удаленные исключительные ситуации, должны теперь поймать соответствующие исключения, перечисленные в таблице 4.3.

Некоторые из этих исключений продублированы в пакете com.mysql.jdbc.exception.jdbc4, это обозначается меткой [jdbc4.] в их именах в таблице 4.3.

Таблица 4.3. Изменения для исключений

Исключение удалено в Connector/J 5.1 Исключение, чтобы поймать в Connector/J 8.0
com.mysql.jdbc.exceptions.jdbc4.CommunicationsException com.mysql.cj.jdbc.exceptions.CommunicationsException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLDataException java.sql.SQLDataException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLIntegrityConstraintViolationException java.sql.SQLIntegrityConstraintViolationException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLInvalidAuthorizationSpecException java.sql.SQLInvalidAuthorizationSpecException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLNonTransientConnectionException java.sql.SQLNonTransientConnectionException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLNonTransientException java.sql.SQLNonTransientException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLQueryInterruptedException com.mysql.cj.jdbc.exceptions.MySQLQueryInterruptedException
com.mysql.jdbc.exceptions.MySQLStatementCancelledException com.mysql.cj.jdbc.exceptions.MySQLStatementCancelledException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLSyntaxErrorException java.sql.SQLSyntaxErrorException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTimeoutException java.sql.SQLTimeoutException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTransactionRollbackException java.sql.SQLTransactionRollbackException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTransientConnectionException java.sql.SQLTransientConnectionException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLTransientException java.sql.SQLTransientException
com.mysql.jdbc.exceptions.[jdbc4.]MySQLIntegrityConstraintViolationException java.sql.SQLIntegrityConstraintViolationException

4.4.1.7. Другие изменения

Вот другие изменения в Connector/J 8.0:

4.5. Тестирование Connector/J

Репозиторий исходного кода Connector/J или пакеты с исходным кодом включают обширный набор тестов, содержащий тестовые скрипты, которые могут быть выполнены независимо. Тестовые скрипты разделены на следующие категории:

Связанный файл Ant содержит цели, подобные test, которые могут облегчить процесс запуска тестов Connector/J, см. целевые описания в файле build. Помимо требований для сборки Connector/J из исходных текстов, описанной в разделе 4.3, много тестов также требуют File System Service Provider 1.2 для Java Naming and Directory Interface (JNDI), доступного с http://www.oracle.com/technetwork/java/javasebusiness/downloads/java-archive-downloads-java-plat-419418.html, поместите файлы jar, загруженные оттуда в каталог lib или в любой каталог, указанный в свойстве com.mysql.cj.extra.libs.

Чтобы запустить тест, используя Ant, в дополнение к свойствам, требуемым для раздела 4.3, необходимо установить следующие свойства в файле build.properties или через опцию Ant -D:

После установки этих параметров, запустите тесты следующими способами:

В то время как о результатах испытаний частично сообщает консоль, предоставлены полные отчеты в форматах HTML и XML. Рассмотрите отчет HTML, открыв buildtest/junit/report/index.html. Версия XML отчетов расположена в папке buildtest/junit.

При переходе от Connector/J 5.1 в 8.0 много свойств Ant для тестирования Connector/J были переименованы или удалены, посмотрите раздел 4.4.1.5.