The tool cm jshell is a convenience wrapper around Java's JShell. In short, it adds the CoreMedia classpath to JShell and provides a namespace for accessing a CoreMedia system via Unified API. To get to know details on JShell please read the corresponding documentation, as for example the Java Shell User’s Guide (Java 21). Find the UAPI Javadoc at https://documentation.coremedia.com/cmcc-12 following the CMS Javadoc link.

Security Concerns

The JShell is a powerful tool, which allows you to execute arbitrary Java code. Thus, it is important to be aware of security concerns when using it. For details, ensure that you have read and understood the details in the Section “Security Concerns”.

Java Development Kit or Module jdk.jshell Required

JShell is shipped with the Java Development Kit (JDK) only. It is not shipped with the Java Runtime Environment (JRE). Ensure, that you are either using a JDK or enabled module jdk.jshell in your environment.

A corresponding failure is shown when starting cm jshell when JShell is not available, mentioning the requirements.

Command Line Options

As cm jshell wraps the standard JShell, all command line options of the original JShell are supported. Thus, you may get an overview of all options calling cm jshell --help. The resulting help text also lists some augmented options provided by the CoreMedia JShell Wrapper JShellLauncher.

These extra options, despite an augmented --startup flavor are:

Options Requiring Write Permissions

The --ask-password option as well as using the CoreMedia Namespace via the --startup COREMEDIA require write access to the temporary folder (as defined by java.io.tmpdir).

You may set another temporary folder to use by passing the runtime system property java.io.tmpdir via command line option -J-Djava.io.tmpdir=<path>.

CoreMedia Namespace

cm jshell comes with a startup script, which behaves similar to JShell's built-in scripts DEFAULT, JAVASE and PRINTING. The startup script is named COREMEDIA.

Different to JShell's built-in scripts, you cannot reference COREMEDIA within JShell and it must be added via --startup command line option.

Imports: COREMEDIA provides a bunch of imports, like for example com.coremedia.cap.common.* and com.coremedia.cap.content.*. For a list of all provided imports, call /imports within JShell.

Namespace: COREMEDIA defines a namespace (represented as variable), which provides some convenience for connecting to a CoreMedia system. There are two variables, which represent the very same namespace: coremedia, and a short version called cm.

Help: To get help for how to use this namespace, just call coremedia.help(). It will provide an overview of topics, which will guide you through the namespace. Along with that, you will find some examples in Section “Examples”.

Initial Connection Setup

Unless you specify the command line option --no-connect, the coremedia namespace will try to establish a connection during the startup phase based on properties as described in Section 3.13.1, “Unified API Spring Boot Client Properties” in Deployment Manual, such as repository.url, for example. Property sources are considered in the following order:

Speed Up using --no-connect

If you want to utilize the coremedia namespace, but are just interested in the imports and the namespace, and not in establishing an initial connection, you may want to consider using the --no-connect command line option. This will skip an automatic connection probe.

For later connection setup, you may use the coremedia.connect() method.

User Properties

The application context set up by the coremedia namespace adds a user properties file to the list of property sources with the lowest precedence. By default, this file is expected to be located in your home folder, and it is named either:

To use a custom location of the user properties file, you can use the command line option --config <cfg>.

Typical properties, for example, include repository.url, repository.user, and repository.password. For more details on the properties, see Section 3.13.1, “Unified API Spring Boot Client Properties” in Deployment Manual.

Custom Properties

On successful connection, the coremedia namespace will provide an application context, that can now be queried for any properties including those provided in the user properties file.

You may, of course, add your own properties to the user properties file and use them in your JShell scripts.

Password Prompt

In untrusted environments, you should not expose your password, neither in system properties provided via command line, nor in user properties. One option to use instead is triggering a password prompt when invoking cm jshell. Another option to consider is using environment variables such as REPOSITORY_PASSWORD.

The password prompt is triggered via command line option --ask-password.

Deprecation Notice

With the introduction of the --ask-password command line the previous approaches using the system property repository.password.query or the environment variable REPOSITORY_PASSWORD_QUERY are deprecated. (since 2506.0).

JShell Options Visible in Process Lists

If you pass the password, for example, via remote system properties using -R-Drepository.password=secret, this will be visible in the process list of your operating system (e.g., via ps command on Linux or macOS, or jps command that comes with the JDK).

Examples

Below you will find some examples in addition to the internal help available via coremedia.help() within JShell. In Shell examples, commands are prefixed with $, while in JShell examples, commands are prefixed with jshell>.

$ cm jshell

Example 3.26, “ Start JShell (Default) ”: Starts the JShell and automatically runs the startup scripts DEFAULT (from JShell) and COREMEDIA. The latter one provides CoreMedia imports as well as the coremedia namespace.

$ cm jshell --startup COREMEDIA

Example 3.27, “ Virtual Built-In Startup Script: COREMEDIA ”: Starts the JShell and runs startup scripts COREMEDIA only.

$ cm jshell --startup DEFAULT

Example 3.28, “ Restrict to DEFAULT ”: If you specify startup scripts explicitly not adding COREMEDIA, neither CoreMedia imports will be provided nor the coremedia namespace. This is very similar to starting the default JShell directly, with exception to the classpath, which includes the CoreMedia classpath.

$ cm jshell \
  -R"-Drepository.url=http://localhost:40180/ior" \
  -R"-Drepository.user=admin" \
  -R"-Drepository.password=admin"

Example 3.29, “ Connection at Startup (System Properties) ”: Starts the JShell and directly sets up a connection to the Content Server given by system properties. The connection will be available via coremedia.connection.

$ export REPOSITORY_URL=http://localhost:40180/ior
$ export REPOSITORY_USER=admin
$  REPOSITORY_PASSWORD=admin cm jshell

Example 3.30, “ Connection at Startup (Environment Variables) ”: Starts the JShell and directly sets up a connection to the Content Server given by environment variables. The connection will be available via coremedia.connection.

Note the extra space character in the command line, when passing the password. For shells such as bash this will prevent the command (and thus the password) to be visible in the command history (unless you changed the corresponding settings).

$ cm jshell

jshell> coremedia.connect(
  "http://localhost:40180/ior",
  "admin",
  "admin")

jshell> coremedia.connection.getContentRepository()

Example 3.31, “ Connection within JShell ”: You may always initiate a connection using the method coremedia.connect. Just as for the initial connection, the connection is available via coremedia.connection afterwards.

Note, that coremedia.connection and all related fields like coremedia.cr (ContentRepository) will always only refer to the latest established connection. You may open several connections in parallel, but you need to store them in your own variables.

To close the latest established connection, just call coremedia.close().

$ cm jshell

jshell> /exit  42

Example 3.32, “ Exit Code Handling ”: Within JShell or within your JShell script, you may exit JShell using the /exit command. You may specify an exit code which will then be the exit code of cm jshell. The default exit code is 0 (zero).

$ cm jshell

jshell> /save -start mystartup.jsh
jshell> /exit

$ cm jshell --startup ./mystartup.jsh

Example 3.33, “ Save Startup Script ”: If you want to customize the startup procedure, you may save the startup script using the /save command. In the given example the file will be saved to your current working directory. You can start JShell with your customized startup script afterward using --startup. This may also be relevant to reduce the security concerns described in Section “Security Concerns” (see especially TOCTOU (Time-of-Check to Time-of-Use)).

Security Concerns

The JShell is a powerful tool, which allows you to execute arbitrary Java code. Thus, it is important to be aware of security concerns when using it. This section will give you an overview of the security concerns and how to mitigate them.

TOCTOU (Time-of-Check to Time-of-Use): When using the coremedia namespace, you should be aware of its processing details, that opens a possible attack vector in your temporary folder (as defined by java.io.tmpdir). The coremedia namespace will be extracted as a JShell script to your temporary folder, which is then executed by JShell. While it provides a convenient use like a built-in script, it is possible that processes manipulate the script when it is extracted to the temporary folder, but before it is executed by JShell.

Possible countermeasures include: Define a custom temporary folder via -J-Djava.io.tmpdir=<path> command line option, which is not writable by other users, or use JShell's /save -start command to save the script to a secured location. Now, instead of using the extracted script, pass the saved script to JShell using --startup <path> command line option.

Untrusted Scripts: When using the JShell, and especially the auto-connection feature provided by the coremedia namespace, you should be aware that scripts are typically executed with credentials of the user running the JShell script (backed, for example, by the .cm.jshell.properties).

Despite, that you should carefully check the scripts you are executing, you may skip specifying the password in the user properties file, or in other property sources (system properties, environment variables). Instead, you may enforce an interactive password prompt. The password is passed to the coremedia namespace encrypted. For details see Section “Password Prompt”.