JetBrains PyCharm v1.5.2 serial key or number

2.1.2. Importing Maven Modules

Figure 21. IntelliJ Maven Module Management - Importing Maven modules

Figure 22. IntelliJ Maven Module Management - Importing another Module

Figure 23. IntelliJ Maven Module Management -

Figure 24. IntelliJ Maven Module Management - Ignoring Modules

Figure 25. IntelliJ Maven Module Management - Ignoring Modules (ctd)

Figure 26. IntelliJ Maven Module Management - Updated Projects Window

2.1.3. Running

Running the App

Once you’ve imported your Isis application, we should run it. We do this by creating a Run configuration, using .

Set up the details as follows:

Figure 27. IntelliJ Running the App - Run Configuration

We specify the to be ; this is a wrapper around Jetty. It’s possible to pass program arguments to this (eg to automatically install fixtures), but for now leave this blank.

Also note that is the webapp module for your app, and that the is .

Next, and most importantly, configure the DataNucleus enhancer to run for your goal. This can be done by defining a Maven goal to run before the app:

Figure 28. IntelliJ Running the App - Datanucleus Enhancer Goal

The flag in the goal means run off-line; this will run faster.

if you forget to set up the enhancer goal, or don’t run it on the correct (dom) module, then you will get all sorts of errors when you startup. These usually manifest themselves as class cast exception in DataNucleus.

You should now be able to run the app using . The same configuration can also be used to debug the app if you so need.

Running the Unit Tests

The easiest way to run the unit tests is just to right click on the module in the Project Window, and choose run unit tests. Hopefully your tests will pass (!).

Figure 29. IntelliJ Running the App - Unit Tests Run Configuration

As a side-effect, this will create a run configuration, very similar to the one we manually created for the main app:

Figure 30. IntelliJ Running the App - Unit Tests Run Configuration

Thereafter, you should run units by selecting this configuration (if you use the right click approach you’ll end up with lots of run configurations, all similar).

Running the Integration Tests

Integration tests can be run in the same way as unit tests, however the module must also have been enhanced.

One approach is to initially run the tests use the right click on the module; the tests will fail because the code won’t have been enhanced, but we can then go and update the run configuration to run the datanucleus enhancer goal (same as when running the application):

Figure 31. IntelliJ Running the App - Integration Tests Run Configuration

2.1.4. Hints and Tips

Plugins

You might want to set up some additional plugins. You can do this using (or equivalently ).

Some others you might like to explore are:

Figure 32. IntelliJ Plugins

Maven Helper Plugin

This plugin provides a couple of great features. One is better visualization of dependency trees (similar to Eclipse).

If you open a file, you’ll see an additional "Dependencies" tab:

Clicking on this gives a graphical tree representation of the dependencies, similar to that obtained by , but filterable.

The plugin also provides the ability to easily run a Maven goal on a project:

This menu can also be bound to a keystroke so that it is available as a pop-up:

Troubleshooting

When a Maven module is imported, IntelliJ generates its own project files (suffix ), and the application is actually built from that.

Occasionally these don’t keep in sync (even if auto-import of Maven modules has been enabled).

To fix the issue, try: * reimport module * rebuild selected modules/entire project * remove and then re-add the project * restart, invalidating caches * hit StackOverflow (!)

One thing worth knowing; IntelliJ actively scans the filesystem all the time. It’s therefore (almost always) fine to build the app from the Maven command line; IntelliJ will detect the changes and keep in sync. If you want to force that, use , .

If you hit an error of "duplicate classes":

then make sure you have correctly configured the annotation processor settings. Pay attention in particular to the "Production sources directory" and "Test sources directory", that these are set up correctly.

2.1.5. Running Integration Tests

2.1.6. Advanced

Setting up Dynamic Reloading

DCEVM enhances the JVM with true hot-swap adding/removing of methods as well as more reliable hot swapping of the implementation of existing methods.

In the context of Apache Isis, this is very useful for contributed actions and mixins and also view models; you should then be able to write these actions and have them be picked up without restarting the application.

Changing persisting domain entities is more problematic, for two reasons: the JDO/DataNucleus enhancer needs to run on domain entities, and also at runtime JDO/DataNucleus would need to rebuild its own metamodel. You may find that adding actions will work, but adding new properties or collections is much less likely to.

To set up DCEVM, download the appropriate JAR from the github page, and run the installer. For example:

Be sure to run with appropriate privileges to be able to write to the installation directories of the JDK. If running on Windows, that means running as .

After a few seconds this will display a dialog listing all installations of JDK that have been found:

Select the corresponding installation, and select .

In IntelliJ, register the JDK in dialog:

Finally, in the run configuration, select the patched JDK:

MariaDB Connector/J is used to connect applications developed in Java to MariaDB and MySQL databases using the standard JDBC API. The library is LGPL licensed.

About MariaDB Connector/J

MariaDB Connector/J is a Type 4 JDBC driver. It was developed specifically as a lightweight JDBC connector for use with MariaDB and MySQL database servers. It was originally based on the Drizzle JDBC code with numerous additions and bug fixes.

Server Compatibility

MariaDB Connector/J is compatible with all MariaDB and MySQL server versions 5.5.3 and later.

Java Compatibility

To determine which MariaDB Connector/J release series would be best to use for each Java version, please see the following table:

To determine which Java versions each MariaDB Connector/J release series supports, please see the following table:

Installing MariaDB Connector/J

MariaDB Connector/J can be installed using Maven, Gradle, or by manually putting the file in your . See Installing MariaDB Connector/J for more information.

MariaDB Connector/J files and source code tarballs can be downloaded from the following URL:

MariaDB Connector/J files can also be downloaded from the following URL:

Installing Dependencies

JNA (net.java.dev.jna:jna) and JNA-PLATFORM (net.java.dev.jna:jna-platform) 4.2.1 or greater are also needed when you would like to connect to the server with Unix sockets or windows pipes.

Using the Driver

The following subsections show the formatting of JDBC connection strings for MariaDB and MySQL database servers. Additionally, sample code is provided that demonstrates how to connect to one of these servers and create a table.

Getting a New Connection

There are two standard ways to get a connection:

Using DriverManager

The preferred way to get a connection with MariaDB Connector/J is to use the class. When the class is used to locate and load MariaDB Connector/J, the application needs no further configuration. The class will automatically load MariaDB Connector/J and allow it to be used in the same way as any other JDBC driver.

For example:

Having MariaDB and MySQL Drivers in the Same Classpath

MariaDB Connector/J permits connection URLs beginning with both and .

However, if you also have MySQL's JDBC driver in your , then this could cause issues. To permit having MariaDB Connector/J and MySQL's JDBC driver in your at the same time, MariaDB Connector/J 1.5.9 and later do not accept connection URLs beginning with if the option is set in the connection URL.

For example, the following connection URL would not be accepted by MariaDB Connector/J:

This allows you to have MariaDB Connector/J and MySQL's JDBC driver in your at the same time.

Using a Pool

Another way to get a connection with MariaDB Connector/J is to use a connection pool.

MariaDB Connector/J provides 2 different Datasource pool implementations:

• : The basic implementation. It creates a new connection each time the method is called.
• : A connection pool implementation. It maintains a pool of connections, and when a new connection is requested, one is borrowed from the pool.

Internal Pool

The driver's internal pool configuration provides a very fast pool implementation and deals with the issues most of the java pool have:

• 2 different connection states cleaning after release
• deals with non-activity (connections in the pool will be released if not used after some time, avoiding the issue created when the server closes the connection after @wait_timeout is reached).

See the pool documentation for more information.

External pool

When using an external connection pool, the MariaDB Driver class must be configured.

Example using hikariCP JDBC connection pool :

Please note that the driver class provided by MariaDB Connector/J is not but !

The class can be used when the pool datasource configuration only permits the java.sql.Datasource implementation.

Connection Strings

The format of the JDBC connection string is:

HostDescription:

Some notes about this:

• The host must be a DNS name or IP address.
• If the host is an IPv6 address, then it must be inside square brackets.
• The default port is .
• The default type is .
• If the failover and load-balancing mode is set to , then the connector assumes that the first host is master, and the others are slaves by default, if their types are not explicitly mentioned.

Examples:

Failover and Load-Balancing Modes

Failover and Load-Balancing Modes were introduced in MariaDB Connector/J 1.2.0.

See failover description for more information.

Optional URL Parameters

General remark: Unknown options are accepted and silently ignored.

The following options are currently supported.

Essential Parameters

TLS Parameters

more information on Using TLS/SSL with MariaDB java connector

Pool Parameters

See the pool documentation for pool configuration.

Log Parameters

Infrequently Used Parameters

Failover and Load Balancing Parameters

JDBC API Implementation Notes

"LOAD DATA INFILE"

The fastest way to load lots of data is using LOAD DATA INFILE.
However, using "LOAD DATA LOCAL INFILE" (ie: loading a file from the client) may be a security problem :

• A "man in the middle" proxy server can change the actual file requested from the server so the client will send a local file to this proxy.
• if someone can execute a query from the client, he can have access to any file on the client (according to the rights of the user running the client process).

A specific option "allowLocalInfile" (default to true) can deactivate functionality on the client side. The global variable local_infile can disable LOAD DATA LOCAL INFILE on the server side.

A non-JDBC method can permit using this kind of query without this security issue: The application has to create an InputStream with the file to load. If MariaDbStatement.setLocalInfileInputStream(InputStream inputStream) is set, the inputStream will be sent to the server, replacing the file content (working even with the "allowLocalInfile" option disabled).

Code example:

Since 1.5.0, Interceptors can now filter LOAD DATA LOCAL INFILE queries according to the filename.

These interceptors must implement the interface. Interceptors use the ServiceLoader pattern, so interceptors must be defined in the META-INF/services/org.mariadb.jdbc.LocalInfileInterceptor file.
Example : Create the META-INF/services/org.mariadb.jdbc.LocalInfileInterceptor file with content org.project.LocalInfileInterceptorImpl.

You can avoid defining the META-INF/services file using google auto-service framework Using the previous example, just add , and your interceptor will be automatically defined.

Set a Query Timeout

Driver follow the JDBC specifications, permitting Statement.setQueryTimeout() for a particular statement.

If the goal is to set a timeout for all queries, since MariaDB 10.1.1, the server permits a limiting query time by setting the system variable max_statement_time.

This solution will handle query timeout better (and faster) than java solutions (JPA2, "javax.persistence.query.timeout", Pools integrated solution like tomcat jdbc-pool "queryTimeout"...).

Option "sessionVariables" permit to set this system variable easily : Example :

Streaming Result Sets

By default, will read the full result set from the server. With large result sets, this will require large amounts of memory.

To avoid using too much memory, rather use Statement.setFetchSize(int numberOfRowInMemory) to indicate the number of rows that will be stored in memory
Example :
using indicates that 1000 rows will be stored in memory.
So, when the query has executed, 1000 rows will be in memory. After 1000 , the next 1000 rows will be stored in memory, and so on.

Note that the server usually expects clients to read off the result set relatively quickly. The net_write_timeout server variable controls this behavior (defaults to 60s). If you don't expect results to be handled in this amount of time there is a different possibility:

• With >= MariaDB 10.1.2, you can use the query "SET STATEMENT net_write_timeout=10000 FOR XXX" with XXX your "normal" query. This will indicate that specifically for this query, net_write_timeout will be set to a longer time (10000 in this example).
• for older servers, a specific query will have to temporarily set net_write_timeout ("SET STATEMENT net_write_timeout=..."), and set it back afterward.
• if your application usually uses a lot of long queries with fetch size, the connection can be set using option "sessionVariables=net_write_timeout=xxx"

Even using setFetchSize, the server will send all results to the client.

Before version 1.4.0, the only accepted value for fetch size was (equivalent to ). This value is still accepted for compatilibity reasons but rather use , since according to JDBC the value must be >= 0.

Prepared Statements

The driver uses server prepared statements as a standard to communicate with the database (since 1.3.0). If the "allowMultiQueries" or "rewriteBatchedStatements" options are set to true, the driver will only use text protocol. Prepared statements (parameter substitution) is handled by the driver, on the client side.

CallableStatement

Callable statement implementation won't need to access stored procedure metadata (mysql.proc) table if both of following are true

• CallableStatement.getMetadata() is not used
• Parameters are accessed by index, not by name

When possible, following the two rules above provides both better speed and eliminates concerns about SELECT privileges on the mysql.proc table.

Optional JDBC Classes

The following optional interfaces are implemented by the org.mariadb.jdbc.MariaDbDataSource class : javax.sql.DataSource, javax.sql.ConnectionPoolDataSource, javax.sql.XADataSource

careful : org.mariadb.jdbc.MySQLDataSource doesn't exist anymore and should be replaced with org.mariadb.jdbc.MariaDbDataSource since v1.3.0

Usage Examples

The following code provides a basic example of how to connect to a MariaDB or MySQL server and create a table.

Creating a Table on a MariaDB or MySQL Server

Services

The driver implements 3 kinds of services:

• Credential service: permit giving credential
• Authentication service: permit adding client authentication plugins.
• SSL factory service: custom TSL implementation

Credential service

Credentials are usually set using user/password in the connection string or by using DriverManager.getConnection(String url, String user, String password).

Credential plugins permit to provide credential information from other means. Those plugins have to be activated setting option `credentialType` to designated plugin.

The driver has 3 default plugins :

AWS IAM

This permits AWS database IAM authentication. The plugin generate a token using IAM credential and region. Token is valid for 15 minutes and cached for 10 minutes.

To use this credential authentication, com.amazonaws:aws-java-sdk-rds dependency must be registred in classpath. Implementation use SDK DefaultAWSCredentialsProviderChain and DefaultAwsRegionProviderChain to get IAM credential and region. see DefaultAWSCredentialsProviderChain and DefaultAwsRegionProviderChain to check how those information can be retrieved (environment variable / system properties, files, ...)

Example:

with AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_REGION environment variable set.

Environment

User and Password are retrieved from environment variables. default environment variables are MARIADB_USER and MARIADB_PWD, but can be changed by setting additional option `userKey` and `pwdKey`

Example : using connection string user and password will be retrieved from environment variable MARIADB_USER and MARIADB_PWD.

Property

User and Password are retrieved from java properties. default property name are mariadb.user and mariadb.pwd, but property names can be changed by setting additional option `userKey` and `pwdKey`

Example : using connection string user and password will be retrieved from java properties `mariadbUser` and `mariadbPwd`

Authentication service

Client authentication plugins are now defined as services. This permits to easily add new client authentication plugins.

List of authentication plugins in java connector :

• mysql_clear_password
• auth_gssapi_client
• client_ed25519
• mysql_native_password
• mysql_old_password
• dialog (PAM)
• sha256_password
• caching_sha2_password

New authentication plugins can be created implementing interface org.mariadb.jdbc.authentication.AuthenticationPlugin, and listing new plugin in a META-INF/services/org.mariadb.jdbc.authentication.AuthenticationPlugin file.

SSL factory service

Custom SSL implementation can be used implementing A connection to a server initially creates a socket. When set, SSL socket is layered over this existing socket. Implementing org.mariadb.jdbc.tls.TlsSocketPlugin permit to provide custom SSL implementation for example create a new HostnameVerifier implementation.

Custom implementation need to implement org.mariadb.jdbc.tls.TlsSocketPlugin and register service META-INF/services/org.mariadb.jdbc.tls.TlsSocketPlugin

Custom implementation are activated using option `tlsSocketType`

Debugging

There is 2 options that can permit to debug :

• the option "enablePacketDebug"
• logging options

Using the Option "enablePacketDebug"

When any connection exception occurs, the stacktrace will a lot more verbose, containing the last 16 truncated exchanges with the server.

Example:

Using Logging Options

The driver relies on the Slf4j framework. Slf4j is an abstraction for logging, which permits using the logger implementation of your choice.

Dependencies must be set using maven or be defined in the classpath.

Example using Logback implementation and maven :

Configurations are implementation dependant, but, most of them need to indicate the package name that have to be logged, and log level. Driver package is "org.mariadb.jdbc".

Log levels on slf4j are trace, debug, info, warn or error.

Example of configuring "trace" level on driver for logback: file logback.xml in src/main/resources/

The last step is to indicate driver to generate logging, setting options "profileSql" or "log" to true.

Exemple of generated logs :

Continuous Integration and Automated Tests

For MariaDB Connector/J's continuous integration and automated test results, please see MariaDB Connector/J's Travis CI.

MariaDB Connector/J's automated tests are run against the following MariaDB versions:

MariaDB Connector/J's automated tests are run with the following Java versions:

• Oracle JDK 6
• Oracle JDK 7
• Oracle JDK 8
• Oracle JDK 11
• OpenJDK 6
• OpenJDK 7
• OpenJDK 8
• OpenJDK 11

Reporting Bugs

If you find a bug, please report it via the CONJ project on MariaDB's Jira bug tracker.

Source Code

The source code is available at the mariadb-connector-j repository on GitHub.

License

GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

For licensing questions, see the Licensing FAQ.

F.A.Q.

Error "Could not read resultset: unexpected end of stream, read 0 bytes from 4"

There is an issue communicating with the server.

Most of the time this will be caused by reading a query that has a large resultset; the server usually expects clients to read off the result set relatively quickly. The net_write_timeout server variable controls this behavior (defaults to 60s). If the client doesn't read the whole resultset in that amount of time, the server will discard the connection. If you don't expect results to be handled in this amount of time there is another possibility:

• if your server version >= MariaDB 10.1.2, you can use the query "SET STATEMENT net_write_timeout=10000 FOR XXX" with XXX being your "normal" query. This will indicate that specifically for this query, net_write_timeout will be set to a longer time (10000 in this example).
• for older servers, a specific query will have to temporarily set net_write_timeout ("SET STATEMENT net_write_timeout=..."), and set it back afterward.
• if your application usually uses a lot of long queries with fetch size, the connection can be set using the "sessionVariables=net_write_timeout=xxx" option.

How to Do a Lightweight Ping / Avoid Mass "select 1"

Connection.isValid() is a good approach. Connection.isValid() is doing a ping (ping in mysql protocol, not network ping). Connection pool using JDBC4 Validation are using automatically this Connection.isValid()

Generating Your SSH Public Key