This guide covers useful setup, resources and resolutions to typical issues encountered in Intellij IDEA when developing the Quantexa solution.
Importance of setting up Intellij IDEA
Intellij IDEA is an Integrated Development Editor (IDE). An IDE comes with more features than a typical text editor to improve software development workflow. Some advantages are:
- Refactoring: Intellij IDEA offers automatic refactoring capabilities, which makes tasks such as renaming (both definitions and uses), extracting and deleting of files and directories easy and safe.
- Code completion: Autocompletion capabilities for Intellij IDEA is an extremely useful feature. It hints and predicts what you're about to type and autocomplete it for you, which makes coding faster.
- Code inspection: There is a set of code inspections that Intellij IDEA performs to detect and correct abnormal code in your project before compilation.
- Debugger: A debugger is a tool developers use to watch and control how the program runs. Intellij IDEA's debugger allows you to stop code execution at various parts of your program to check variables values and confirm code logic.
These are just a couple of advantages. In addition to the extensive settings available from the base product, Intellij IDEA can also be customized with community made plugins to further enhance your productivity and smoothen your developer experience.
Useful information
There are 4 important directories to be aware of:
- Configuration Directory
The IntelliJ IDEA configuration directory contains user-defined IDE settings, such as keymaps, color schemes and more importantly, custom VM options. - System Directory
The IntelliJ IDEA system directory contains caches and local history files. - Plugins Directory
The IntelliJ IDEA plugins directory contains user-installed plugins, either downloaded from the Marketplace or manually added. - Logs Directory
The IntelliJ IDEA logs directory contains product logs and thread dumps.
On some client laptops and developer environments, there might be insufficient space or permission issues when Intellij IDEA writes to the default locations of the above-mentioned directories. You can relocate these by following the steps in the official documentation.
Setup Essentials
Java and Gradle
When encountering issues with Java and Gradle, it is wise to first differentiate between a Java/Gradle setup issue or an Intellij IDEA setup issue. When in doubt, run the equivalent gradlew or gradle command in a new, separate terminal instance (not the terminal within Intellij IDEA). If it fails, chances are that there is an underlying issue with the Java/Gradle setup. That should be addressed first before attempting any fix in Intellij IDEA.
Java in Intellij IDEA
To ensure that Intellij IDEA is using the correct Java SDK version, you can check the version in use by navigating to File | Project Structure.
Figure 1.1: Setting up Project SDK to use correct Java SDK Version
Ensure that the correct Java SDK version is selected. The Java version selected should be the same as the Java version on your terminal which successfully runs gradlew or gradle.
Your Java SDK might not be detected by Intellij IDEA. To add it in, navigate to File | Project Structure | Platform Settings | SDKs. You can proceed to add the specific Java SDK in Intellij IDEA and select the correct SDK version instead.
Figure 1.2: Adding a Java SDK on your machine to Intellij IDEA
Gradle in Intellij IDEA
If the command works in the terminal but fails in Intellij IDEA, in Intellij IDEA, navigate to Settings | Build | Execution | Deployment | Build Tools | Gradle.
Figure 1.3: Setting up Gradle in Intellij IDEA
Ensure that the following are aligned:
- Gradle user home should be set to
C:/Users/<UserName>/.gradle or ~/.gradle, or the value of environment variable GRADLE_USER_HOME. - Gradle distribution should be set to:
- Wrapper if using the Gradle wrapper to run Gradle commands for the project. (i.e.
.\gradlew build or gradlew build) - Local Installation if using locally installed Gradle. (i.e.
gradle build)- If using
gradle, ensure that the Gradle location is set to the same executable in your PATH environment variable.
- Set the Gradle JVM to use the same Java version as the value of environment variable
JAVA_HOME.
Java and Gradle setup tips
- After changing any environment variables or options in Intellij IDEA, it is wise to restart it so that new environment variables are inherited on relaunch.
- If you have successfully built the project in the terminal, you can enable Offline Mode in Intellij IDEA which will reuse the cached jars when subsequently importing the project.
- One of the factors impacting selection of the Java SDK version for Gradle is the expected Gradle version used in the project. Refer to the official Gradle documentation's compatibility matrix for more details.
- If you are using a local installation of Gradle, ensure that the installed version of Gradle on your local system matches the declared Gradle version in your project's
gradle.properties file.
Figure 1.4: Inspecting gradle.properties to identify the expected Gradle version for the project
Scala plugin
The Scala plugin adds support for the Scala language in Intellij IDEA. Coding assistance features such as highlighting, completion, formatting and refactoring for the Scala language would be made available after plugin installation.
There are two ways to install the Scala Plugin:
Using the Plugins Marketplace
- Navigate to Settings | Plugins and search for Scala.
- Install the Scala plugin. You may be required to restart Intellij IDEA for the plugin to take effect.
Figure 2.1: The Plugins page in Intellij IDEA
Installing the plugin manually
- Navigate to the Scala plugin versions page.
- Select the Intellij IDEA Community option (or whatever distribution of Intellij IDEA you are using) on the Compatibility dropdown.
- Download the latest Scala plugin version compatible with your Intellij IDEA Community version. This should download a ZIP file.
- Import the ZIP file by selecting the Settings (Gear icon) followed by Install Plugin from Disk.
Figure 2.2: Importing a plugin manually
Importing a project
Typically, a project is imported by opening the project root in Intellij IDEA. The Gradle plugin should automatically begin the importing process. When doing this for the first time, it can take a long time for Intellij IDEA to index the entire project.
In the event any build.gradle file is modified, the Refresh Gradle Dependencies symbol (circled in orange) would appear to prompt you to re-import the project. To manually begin the re-import process, select the Sync All Gradle Projects symbol (circled in purple).
Figure 2.3: Depiction of the Refresh Gradle Dependencies and Sync All Gradle Projects symbol
Troubleshooting Common Issues
Memory issues
Description
Out of memory issues might be encountered while using Intellij IDEA. The following is an example of the error message received. Be aware that you could encounter out of memory issues for the underlying Gradle process rather than Intellij IDEA itself. An example of out of memory issues arising within Intellij IDEA:
Caused by: java.lang.OutOfMemoryError: Java heap space: failed reallocation of scalar replaced objects
Listing 2.4: Error message depicting insuffient memory in Intellij IDEA
Resolution
Increase the memory heap of Intellij IDEA.
Figure 3.1: Increasing Maximum Heap Size setting in Intellij IDEA
- In the main menu, go to Help | Change Memory Settings.
- Increase the amount of memory to allocate based on your computer's specifications and click Save and Restart.
Import Issues
Description
There could a variety of reasons for import failures. Ensure you have followed the Setup Essentials part of this blog to eliminate any Intellij IDEA configuration issues. If issue persists, Intellij IDEA might require caches to be cleared to import the project properly.
Resolution
Invalidate Intellij IDEA caches.
Figure 3.2: Invalidating Caches for Intellij IDEA
- Navigate to File | Invalidate Caches…
- Select relevant options and select Invalidate and Restart. Typically, all 4 checkboxes are selected.
If the above does not solve the problem, consider doing a fresh import of the project. This can be done by deleting the .idea directory located at project root and opening the project again in Intellij IDEA. If there are issues in running the typical gradlew or gradle commands when it was working previously without change in any .gradle files, consider deleting the .gradle directory at project root.
Formatters
If you encounter code that is not properly formatted, IntelliJ IDEA can reformat the code to project specification. In the file you want to reformat, use the shortcut ⌘⌥L (macOS) / Ctrl+Alt+L (Windows/Linux). The setup for formatters are covered below.
Scalafmt
When the Scala plugin is installed in Intellij IDEA, it comes with the option to use Scalafmt as the code formatter for all Scala files (files ending in .scala). It is recommended to use Scalafmt as the default formatter as it integrates well with Gradle through the Spotless plugin.
Once installed, navigate to Editor | Code Style | Scala. Ensure that the Scalafmt option is selected under Formatter.
Figure 4.1: Selecting the formatter type for Scala in Intellij IDEA
All Quantexa code repositories come with a .scalafmt.conf file which specifies the formatting options for the project.
For more details, check out Intellij IDEA's documentation on Scalafmt.
HOCON
Many of Quantexa's configuration files are in HOCON format. You can use the HOCON plugin to ensure consistent formatting of your project files.
- Install the HOCON plugin.
- Navigate to File | Settings | Editor | Code Style | HOCON to set the desired configuration for HOCON files.
- Navigate to File | Settings | Editor | File Types | HOCON to add file name patterns corresponding to Quantexa-specific file types. Examples include
.qdocuments , .qentity and .qmodel. This ensures that the HOCON formatter will be applied to files of the corresponding extensions when the shortcut to reformat the file is triggered.
Figure 4.2: Adding file name patterns to identify HOCON type files
For more details, check out HOCON's GitHub README.
Useful plugins
Here are some useful plugins you could consider adding to improve the development experience.
- Archive Browser
- This allows you to see the contents of JAR and ZIP files in Intellij IDEA project files. Useful to check if built JAR files contains the expected content.
- Indent Rainbow
- Makes viewing indentation easier through use of colors.
- Rainbow Brackets
- Shows matching brackets in the same color.
- IdeaVim
- Enables use of vi keybindings in Intellij IDEA.
- String Manipulation
- Provides ways to further manipulate text such as switching casing styles, sorting, filtering and incrementing numbers.
- Avro and Parquet Viewer
- A tool window useful for viewing Parquet files and their schemas quickly.
Closing thoughts
Setting up IntelliJ IDEA empowers developers to write, test, and debug code with ease. By following the steps outlined in this guide, you've laid the foundation for a productive coding experience.
Remember to tailor your IntelliJ IDEA setup to suit your specific project needs, whether by installing additional plugins, configuring themes, or customizing key mappings. With its vast array of tools and integrations, IntelliJ IDEA is designed to adapt to your workflow, helping you focus on what matters most: creating great software.
Now that your development environment is ready, dive into your project and start programming with confidence. Happy hacking!
📝 Note: If you have registered for the Quantexa Community, you can also access the Documentation Site. If you have any issues accessing the Docs site please reach out to community@quantexa.com
