Definition

A container executing in the same JVM where Cargo is running

Explanation

An embedded container means that Cargo is using directly the container's Java API to control it and starts the container in the same JVM as where it is running. This implies you can do many advanced things programmatically - such as playing with the class loader, adding proxy classes, etc.

Please note that if you're using one of the embedded implementation you'll need to ensure that you have the container's JARs in your classpath.

Embedded containers, since they run in an existing JVM, will come with a large number of limitations:

  • Any existing JVM setting, such as JVM properties or debuggers, will be inherited from the parent JVM and cannot be changed.
  • Some features such as logging might not work as expected as they inherit existing Java logger settings.
  • You might very quickly run into a JAR hell. While the Cargo samples' EmbeddedContainerClasspathResolver.java might give you ideas on how to avoid it, this might not work in all circumstances.
  • If you are using either the ANT tasks or Maven2/Maven3 plugin, the container will most likely inherit even more "uncontrollable" items that come from these tools.
  • When using embedded containers with the Maven2/Maven3 plugin, Cargo will be deciding on the version of the container you use - and you cannot change it.
  • Again when using embedded containers with the Maven2/Maven3 plugin, Cargo will only load a minimal set of dependencies and advanced features might be missing.
  • Some containers contain classed that have final attributes defined on certain classes, that remain set to their updated values even if you reset the class loader - The only way to revert this is to restart the JVM. This implies that:

    • It might not possible to execute different versions of these containers in the same JVM

    • It might also not be possible to run two embedded container instances one after the other within the same JVM but different classpaths

As a result, except in cases where you have a compelling reason to use an embedded container, please use an Installed Container instead.