--- schema_version: "1" id: cb29d7495dc2195cb7a1a307f3a0452d8132ffc76fd9cdd4b30ef3c0c50b720a title: Class-loading Isolation collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/mule-runtime/4.9/about-classloading-isolation.md canonical_url: https://docs.mulesoft.com/mule-runtime/4.9/about-classloading-isolation source_site: docs.mulesoft.com content_type: documentation content_hash: 4e0fbde03b571c272306ca50f4b757a94873759e421cb062793b87293f662e8a description: MuleSoft Documentation Site release: "4.9" latest: false --- --- product: Mule Runtime version: 4.9 --- # Class-loading Isolation > For the full documentation index, see: https://docs.mulesoft.com/llms.txt Mule runtime engine is developed using Java and many other third-party libraries. Mule apps can also contain Java libraries, particularly modules that extend Mule to provide integration functionality, such as Anypoint Connector for HTTP and the XML module. These extension modules can also contain Java (JAR) libraries. The default class-loading mechanism of the JVM makes it possible to have conflicting versions of the same JAR files. In Mule, each artifact (the runtime, the Mule apps, and Mule extensions) is developed and released independently, but the JARs for these artifacts are together in the same location. For example, a Mule app might use Apache Commons Collections 2.1. If an extension you use requires Apache Commons Collections 3.1, the app might not work as expected because Commons Collections 2.1 and Commons Collections 3.1 have conflicting resources. ## API Definition Mule runtime engine and the artifacts (apps, domains, policies, and extensions) need to have a clear API definition that specifies a contract for each artifact and limits the exposure of the artifact content to other artifacts. A clear API for each artifact provides a way to limit the scope of classes and libraries, which in turn makes it possible to create class loaders that do not share everything. ### Mule 4 API Mule 4 provides a well-defined API that makes it easy for you to extend Mule and provides clarity on the proper extension points: - Core API: Mule message. - Extensions API: Modules, message processors, transforms, and other elements to extend Mule Runtime 4. - Tooling API: All DataSense metadata and propagation is now part of Mule Runtime 4. This API is bundled with the Runtime Manager agent. ### Artifact API When you create an artifact (app, domain, policy, or extension), you need to declare the public API of that module. #### How To Define the Public API See [Export Resources](https://docs.mulesoft.com/mule-runtime/4.9/how-to-export-resources) to export a resource from an artifact. #### Considerations - Resources and classes that are not exported are not visible from other artifacts. - Expose the minimum required set of packages and resources from your artifact. - Do not export third-party libraries unless required. - Never expose common third-party libraries like Guava, Apache common-collections, and so on. Doing so will cause clashes with other artifacts. - Ideally, expose only classes from your artifact (or the JDK). ### Semver Mule 4 follows [Semantic Versioning 2.0.0](https://semver.org/) for all the provided APIs. ### API restrictions All public APIs might have restrictions. These restrictions limit how you can use the API. See [API annotations module](https://github.com/mulesoft/api-annotations) for more details. > [!IMPORTANT] You need to take into account the API restrictions defined for the API you are > consuming, as they ensure greater flexibility among API changes that can occur between different > versions. ## Class-loading Isolation Mechanism Once APIs are clearly defined, you can prevent access to internal classes of the artifact and only make the public API accessible from outside. To protect the APIs, Mule 4 uses a custom class-loading mechanism. Consider the following extension file structure: com/example/extension/api/MyClass.class com/example/extension/internal/Util.class transformations/customer-to-user.dwl license.txt META-INF/mule-artifact/mule-artifact.json And the following `mule-artifact.json` descriptor file for the extension: ```json { "name": "my-test-extension", "minMuleVersion": "4.0.0", "classLoaderModelLoaderDescriptor": { "id": "mule", "attributes": { "exportedResources": ["transformations/customer-to-user.dwl"], "exportedPackages": ["com/example/extension/api"] } } } ``` The following diagram shows how resources exported by `mule-artifact.json` are applied within an app: ![A class-loading diagram for a Mule app](/mulesoft/current/en-us/mule-runtime/4.9/_images/simple-classloading-diagram.png) Artifact Class Loader A regular Java class loader pointing to the JAR files included in the extension. This class loader loads all files and classes of the extension. Artifact Filtering Class Loader A wrapper created over the Artifact class loader, which enforces access restrictions to the extension code for foreign artifacts (the app or other plugins). It uses the content of the `mule-artifact.json` descriptor to determine what is public. Extension Code The Mule extension code. Uses the Artifact class loader (which does not have any restriction), and it is only able to locate resources of the plugin itself. Application Code The Mule app code. It uses the Artifact Filtering class loader of the extension to prevent the app from accessing restricted code or resources. ## Adding Dependencies to Connectors When the connectors in your application need access to a dependency in your project, configure the dependency to be visible by the connector’s class loader. There are two different ways to do this: - Configure application dependencies as [shared libraries](#shared-libraries). - Configure [additional plugin dependencies](#additional-plugin-dependencies) for the connector. ### Shared Libraries All dependencies (JAR files, for example) declared in the application’s `pom.xml` file are visible to the application’s class loader but not visible to the class loader of each connector used in the application. The Mule runtime engine class-loading mechanism isolates each connector to prevent it from accessing classes from other connectors. If a connector’s class loader needs access to an application dependency, declare this dependency as a shared library. Consider an application that uses Anypoint Connector for Java, and the connector needs to use a class that is part of a JAR dependency declared in the application’s `pom.xml` file. However, this is not possible, because the connector’s class loader is not able to find that class. To make this class visible to the connector, you must declare the dependency that contains the class as a shared library in the Mule Maven plugin configuration of your application’s `pom.xml` file. If you use Anypoint Studio to configure a connector that uses external libraries, the dependencies are automatically added as shared libraries. For example, if you add Anypoint Connector for Database to your application and then configure the connection driver using Anypoint Studio, the driver is automatically added as a shared library in your project’s `pom.xml` file. See [Configure Shared Libraries](https://docs.mulesoft.com/mule-runtime/4.9/mmp-concept#configure-shared-libraries) for configuration instructions. > [!NOTE] Shared libraries are visible to all connectors in the application. Configuring shared > libraries can cause issues if the shared library has different versions of the same classes in > other connectors or their dependencies. ### Additional Plugin Dependencies Instead of configuring shared libraries to make application dependencies visible to all connectors in the application, you can configure additional plugin dependencies to enrich a specific connector’s classpath. This configuration enables you to effectively add new dependencies to a connector, as if the dependencies were declared in the connector’s `pom.xml` file. Configuring additional plugin dependencies ensures that the dependencies are available only for the configured connector, and you don’t need to declare them as application dependencies. When you configure additional plugin dependencies, you must specify the dependency version. See [Configure Plugin Dependencies](https://docs.mulesoft.com/mule-runtime/4.9/mmp-concept#configure-plugin-dependencies) for configuration instructions. ## See Also - [Mule SDK - About Class-loading Isolation](https://docs.mulesoft.com/mule-sdk/latest/isolation)