Managed Dependencies

Last modified: April 18, 2024

1 Introduction

Mendix Studio Pro allows you to manage your Java dependencies. By specifying Java dependencies and their versions per module, Studio Pro can automatically download them and resolve conflicts by leveraging Gradle.

In versions of Mendix below 10.3.0, Java dependencies were put into the userlib folder manually. This process has been simplified using managed dependencies, although the userlib folder can still be used for custom .jars. For more information see Unmanaged Dependencies, below.

2 Adding or Updating Managed Dependencies

You can specify Java dependencies through the module settings of each module. For each module, you can configure your dependencies on the Java Dependencies tab of Module settings.

The tab shows a list of currently specified Java dependencies for this module. You can add New dependencies and Edit or Delete existing dependencies. Dependencies are identified through their Maven Naming Convention.

To enter a dependency, do the following:

  1. Enter the Group ID, Artifact ID, and Version. For example, org.apache.poi, poi, and 5.2.3.

  2. Click OK to confirm your changes.

    Studio Pro will attempt to retrieve these dependencies. This process is termed ‘synchronization’. The dependencies are downloaded from a central repository and cached locally. The default repository is Maven Central, but custom repositories can also be configured, see Custom Repositories, below. Synchronization will happen in the background so you can continue working in Studio Pro.

2.1 Finding the Right Dependency

Sonatype’s Maven Central Repository is a good place to start to find the proper identifier.

After finding the package of your choice, locate the Snippets part, containing the identifier:

3 Dependency Synchronization

When a change is made to a specified dependency, for example, the dependency is removed or the module is updated from the Marketplace, dependency synchronization will automatically run in the background.

Dependency synchronization also occurs when you open your app in Studio Pro.

You can trigger a manual synchronization in the menu App > Synchronize dependencies. You may want to do this, for example, when synchronization failed due to connectivity issues.

Once Gradle has resolved and downloaded all dependencies successfully, it places them in the vendorlib directory. This directory is used to store .jar files of all the managed dependencies. Unlike the userlib folder, which needs to be updated manually, the vendorlib folder is completely managed by Studio Pro. Files here will automatically be added and removed based on the specified dependencies. The vendorlib folder will be committed to your version control just like the userlib.

Within the vendorlib directory, we also generate the vendorlib-sbom.json file. This is the Software Bill of Materials of the vendorlib directory.

4 Unmanaged Dependencies

Most dependencies can be managed using the managed dependencies feature. However, you may have a custom jar which you are experimenting on, or which is simply not available in any remote repositories. In this case, you can still place these unmanaged .jar files in the userlib folder to make it a dependency of your Mendix app.

5 Migrating from Unmanaged to Managed Dependencies

When you have created a module that contains .jar files in the userlib folder, the best practice is to port these to managed dependencies if the .jars are available in a Maven repository. Add the specified dependency to your module and simply remove the old .jar file from the userlib folder to prevent a conflict.

Platform-supported Marketplace modules created by Mendix have been updated with a custom mechanism to automatically migrate to managed dependencies.

6 Custom Repositories

By default, dependencies are downloaded from the Maven Central repository. In some scenarios, you may want to specify a custom location. For example, if your organization has its own repository to cache downloads or as an alternative if internet access is restricted in an air-gapped setup.

Custom repositories are configured in the Repositories setting of the Deployment tab in the Preferences dialog box. This setting uses the same syntax as Gradle. For internal usage of the platform, some dependencies are required which are also resolved using the configured repositories. For example, to resolve dependencies from a directory lib, enter the following:

flatDir {
    dirs 'lib'
}

By default the repositories are configured as:

gradlePluginPortal()
mavenCentral()

For more details, refer to the Gradle documentation on Declaring repositories.

6.1 Required Dependencies

There are some dependencies that are required by Mendix. These need to be added to your configured repository. Below is a list of these dependencies:

  • The Gradle plugin cyclonedx-gradle-plugin, which generates a Software Bill of Materials (SBoM) required in certain contexts

7 Proxy Settings

Your local setup might be configured to work with a proxy or it could be behind a firewall. This means your system will have restricted access to the internet. In such cases, Gradle cannot access external repositories to download the required dependencies to build the project. You will have to configure Gradle/JVM with the proxy settings on your system for it to be able to build and run the project on your local setup.

Below are the few options you can try to configure Gradle with custom proxy settings:

7.1 Gradle Proxy Settings

You can create a gradle.properties file in the Gradle User Home directory and configure the proxy settings there. Just replace the values in the sample file below with your values. See the official Networking with Gradle guide for further details.

Sample gradle.properties file:

systemProp.http.proxyHost=proxy-host-ip
systemProp.http.proxyPort=proxy-port
systemProp.http.proxyUser=userid
systemProp.http.proxyPassword=password
systemProp.https.proxyHost=proxy-host-ip
systemProp.https.proxyPort=proxy-port
systemProp.https.proxyUser=userid
systemProp.https.proxyPassword=password

If Gradle still fails to download dependencies with the correct proxy settings configured, you can configure the HTTPS/SSL certificate store that Gradle uses.

Add the following lines to the gradle.properties file:

systemProp.javax.net.ssl.trustStore=\\path\\to\\win_ini_file
systemProp.javax.net.ssl.trustStoreType=Windows-ROOT

7.2 VPN Setup

You may have a VPN or firewall that blocks/restricts access to certain websites. In this case, you need to ask your network/system administrators to allow access to the following sites:

  • jcenter.bintray.com
  • plugins-artifacts.gradle.org
  • plugins.gradle.org
  • repo.maven.apache.org

7.3 Java Proxy Settings

If the above options do not work, you can try adding your proxy settings to the JDK proxy settings file. After you reboot your system to apply the settings, Gradle will pick up these settings and will attempt to connect to external repositories through the proxy.

You can find the file your java installation under /conf/net.properties

Sample net.properties file

http.proxyHost=your.proxy.ip.address
http.proxyPort=your.proxy.port
https.proxyHost=your.proxy.ip.address
https.proxyPort=your.proxy.port

If the above options don’t work for you, please reach out to Mendix Support for further assistance.

8 Marketplace Modules

Dependency information is included per module and included in Marketplace Modules. The actual artifacts (.jar files) are not part of the module. They are downloaded to the vendorlib folder automatically when synchronization is run when the module is imported.

If you have an issue with the managed dependencies of a Marketplace module, you can revert to an earlier version by removing the new version and downloading an earlier version from the Marketplace.

9 Troubleshooting

There can be multiple reasons the dependencies cannot be resolved. See the following for some common failure causes with steps on how to fix the issue.

  1. CE9804 – Incorrect specification: the specified dependency could not be found in the configured repository.

    • Check whether you specified the correct Group ID, Artifact ID, and Version. These are case-sensitive.
    • If you are using a custom repository, check whether the dependency exists in the repository.

  2. CE9805 – Network connection failure.

    • Check that you have a working internet connection.
    • If you are using a custom repository, confirm that the repository can be reached.

  3. CE9806 – Unable to reach repository / mis-configuration of custom repository.

  4. CE9807 - Required dependency could not be found in the configured repository.

  5. CE9802 - Java dependency synchronization never done.

    This is just an internal state we maintain for completeness. This should never occur unless something unexpectedly fails in the background in Studio Pro. If you do encounter this, you can try to resolve this by doing either, or both, of the following:

    • Manually synchronizing dependencies once more
    • Restarting Studio Pro

  6. CE9803 – Any failure which is not covered in the above scenarios.

    • Try manually synchronizing dependencies once more.
    • If your setup is configured with a proxy or firewall, you might want to configure these as described in proxy settings, above.
    • Reach out to Mendix Support if the issue persists.