# Embedded JVM configuration

This page describes the configuration items for a C DataSource application’s embedded Java virtual machine (JVM).

For information on configuring the JVM used to run a Java DataSource application, see [Configuring a Java DataSource’s JVM](datasource-configure-a-datasource-applications-jvm.md#java).

## jvm-global-classpath

`jvm-global-classpath` specifies the classpath of a C DataSource’s embedded JVM.

You can specify multiple classpaths on the same line, using a space separator, like this:

```
jvm-global-classpath %r/lib/java/jmx-child-classloader.jar %r/lib/java/common-jmx.jar
```

You can also specify multiple classpaths, using a separate `jvm-global-classpath` item for each one; for example:

```
jvm-global-classpath %r/lib/java/jmx-child-classloader.jar
jvm-global-classpath %r/lib/java/common-jmx.jar
```

The classpath can contain the `%r` parameter; at run time, `%r` is replaced by the root directory ([application-root](datasource-run-time-environment-configuration.md#application-root)) under which the DataSource application runs, so you can define the classpath location relative to this.

You can also specify a classpath for a specific class, using the [classpath](#classpath) option of [add-javaclass](#add-javaclass).

**Use in:** C

**Syntax:** `jvm-global-classpath <classpath>`

**Type:** array of strings

**Default value:** `%r/lib/java`

## jvm-location

`jvm-location` is a C DataSource configuration item that directs the DataSource to run an embedded JVM using a specified JVM library. The embedded JVM is used by the DataSource to host Java modules that extend the DataSource’s functionality (for example, Transformer’s Refiner module).

The JVM location may be specified as an absolute path to a JVM library or a parent directory of a JVM library:

* Absolute path to a JVM library.

  **Example: (RHEL 7) absolute path to an OpenJDK 8 JVM library**

  ```
  jvm-location /etc/alternatives/java_sdk_1.8.0/jre/lib/amd64/server/libjvm.so
  ```
* Absolute path to a parent directory of a JVM library.

  Requires a C Datasource built with DSDK 7.1.16+ (Liberator 7.1.15+, Transformer 7.1.10+, TREP Adapter 7.1.3+).

  **Example: (RHEL 7) absolute path to an OpenJDK 8 installation directory**

  ```
  jvm-location /etc/alternatives/java_sdk_1.8.0
  ```

  **Example: absolute path to the Java installation directory set in the JAVA_HOME environment variable**

  ```
  jvm-location ${ENV:JAVA_HOME}
  ```

The path supplied to `jvm-location` must follow the path-formatting conventions of the operating system for which the C DataSource binary is compiled:

| Operating system | Path format | Example (truncated) |
| --- | --- | --- |
| RHEL | UNIX | jvm-location /etc/alternatives/java_sdk_1.8.0/... |
| macOS | UNIX | jvm-location /Library/Java/JavaVirtualMachines/... |
| Windows 10 | Windows | jvm-location "C:/Program Files/AdoptOpenJDK/..." |

Paths containing spaces should be quoted (see the Windows path above). Windows paths may use forward-slashes as directory separators.

**jvm-location and the Deployment Framework**

In deployments managed by the Deployment Framework, Caplin Platform blades for Java modules use the Deployment Framework’s built-in configuration variable `JVM_LOCATION` to set the value of `jvm-location`:

```
jvm-location ${JVM_LOCATION}
```

The default value of `JVM_LOCATION` is the path to a Java 8 JVM library, derived from the value of the environment variable `JAVA_HOME`. For deployments that require a Java 11 JVM, use the Deployment Framework’s [`**dfw java**`](../deployment-framework/cdf-the-deployment-framework-command-utility-dfw.md#java) command to override the default value of `JVM_LOCATION` with the absolute path to a Java 11 JVM library:

**Example: (RHEL 7) Overriding the default value of JVM_LOCATION with the path to a Java 11 JVM library**

```
$ dfw java /etc/alternatives/java_sdk_11/lib/server/libjvm.so
```

For detailed information on Caplin Platform compatibility with Java 11, see [Caplin Platform System Requirements](../platform-architecture/platform-hardware-and-software-requirements.md).

**Use in:** C

**Syntax:** `jvm-location <path>`

**Type:** string

**Default value:** +[none]+

**Examples**:

* RHEL 7: `jvm-location /etc/alternatives/java_sdk_1.8.0/jre/lib/amd64/server/libjvm.so`
* macOS: `jvm-location /Library/Java/JavaVirtualMachines/adoptopenjdk-11.0.2.jdk/Contents/Home/lib/server/libjvm.dylib`
* Windows 10: `jvm-location "C:/Program Files/AdoptOpenJDK/jdk-11.0.10.9-hotspot/bin/server/jvm.dll"`

## jvm-options

`jvm-options` specifies startup options for a C DataSource application’s embedded JVM. You can specify any of the valid [Java command line options](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/java.html).

You can specify multiple options in one instance of `jvm-options` or use a separate instance of `jvm-options` per startup option. The two examples below are equivalent.

```
jvm-options -Xms256m -Xmx256m
```

```
jvm-options -Xms256m
jvm-options -Xmx256m
```

**Use in:** C

**Syntax:** `jvm-options <java-command-line-options>`

**Type:** array of strings

**Default value:** +[none]+

## add-javaclass

`add-javaclass` specifies the main (entry) class of a C DataSource’s Java module. Java modules are used to extend a C DataSource application’s functionality. See, for example, Transformer’s [Refiner](../transformer/transformer-deploy-the-refiner-service-module.md) module.

For examples of how to use `add-javaclass` within Caplin Platform blades, see:

* [Create a Java-based Transformer Service blade](../deployment-framework/cdf-create-a-java-based-transformer-service-blade.md)
* [Create a Java-based Liberator Permissioning Service blade](../deployment-framework/cdf-create-a-java-based-liberator-permissioning-service-blade.md)
* [Add a custom subject mapper to a Permissioning Service blade](../deployment-framework/cdf-add-a-custom-subject-mapper-to-a-permissioning-service-blade.md)

**Use in:** C

**Syntax:**

```
add-javaclass
   xref:class-id[class-id]     [string]
   xref:class-name[class-name]   [string]
   xref:classpath[classpath]    [array of strings]
end-javaclass
```

**Options**

* **class-id**

  **Type:** string | **Default:** _null_

  A short identifier of the Java class. When the Java module is part of a [Java-based Transformer Service blade](../deployment-framework/cdf-create-a-java-based-transformer-service-blade.md), `class-id` must be set to the blade name.
* **class-name**

  **Type:** string | **Default:** _null_

  The fully-qualified class name of the Java module to load.
* **classpath**

  **Type:** string | **Default:** _null_

  One or more space-separated Java classpaths that define where the class in [class-name](#class-name) is to be loaded from; for example:

  ```
  classpath %r/lib/java/jmx-child-classloader.jar %r/lib/java/common-jmx.jar
  ```

  You can have multiple occurrences of `classpath` in the same `add-javaclass` item. For example, the `classpath` above can be rewritten as two `classpath` options:

  ```
  classpath %r/lib/java/jmx-child-classloader.jar
  classpath %r/lib/java/common-jmx.jar
  ```

---

**See also:**

* How can I... [Configure a DataSource application’s JVM](datasource-configure-a-datasource-applications-jvm.md)
* How can I... [Change the size of the JVM heap](datasource-change-the-size-of-the-jvm-heap.md)