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 consult the corresponding documentation, as for example the Java Shell User’s Guide (Java 11). Find the UAPI JavaDoc at https://documentation.coremedia.com/cmcc-10 following the CMS Javadoc link.

As cm jshell just wraps the standard JShell, all command line options are the same as for the original JShell. Thus, you may get an overview of all options calling cm jshell --help.

Java Development Kit 9+ required

JShell is available since Java version 9. In addition to that, JShell is shipped with the Java Development Kit (JDK) only. It is not shipped with the Java Runtime Environment (JRE).

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

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: First of all, 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

You may start up JShell in a way, that it automatically initializes a connection on startup phase. To do so, you have to provide the connection settings. You may choose one of the following configuration options, or even mix them:

The given order applies to the precedence of properties. Thus, an IOR URL given as system property overrides the IOR URL from environment, whereas a connection password given as environment property overrides the password specified in the properties-file in your home-folder.

Unencrypted Passwords

The passwords provided directly via system properties, environment variables, or user properties are unencrypted. Take care to handle these settings with care, like protecting access to your home-folder or by preventing calls to cm jshell to appear in command-history.

In alternative to this, you may enforce a password prompt. For details see Section “Password Prompt”.

System Properties

The coremedia namespace supports some system properties. To pass them to the JShell environment, you must specify them as remote options, using -R<flag>.

Supported system properties are:

Beware of Untrusted Scripts

You should not pass passwords to untrusted scripts. The system property repository.password will expose the plain-text password within JShell for interactive use, as well as to scripts.

User Properties

All properties described in Section “System Properties” may also be given in a properties-file located in your home folder.

Precedence: Compared to system properties and environment variables, properties in your home folder have the lowest precedence.

Environment Variables

Similar to system properties, you may specify the properties as environment variable. Note, that system properties take precedence. Thus, using system properties you may override any of the following environment variables.

No Access for User-Provided Scripts

cm jshell passes environment variables to the remote script via an encrypted file. The data are exposed to the coremedia namespace only. User-provided remote scripts cannot access these environment variables.

Beware of Untrusted Scripts

You should not pass passwords to untrusted scripts. While the password passed via environment variables is not directly accessible, the system properties will expose details, which attackers may use to decode the password.

Password Prompt

In untrusted environments, you should not expose your password, neither in system properties provided via command-line, nor in environment, nor in user properties. Instead, you may configure cm jshell to prompt for a password.

To do so, you may either set a runtime system property, or you may set an environment property:

If you set any of the two to true, you will be prompted for a password.

Precedence: The password provided this way has a slightly higher precedence than a password provided via environment properties. In other words:

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.27, “ 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.28, “ Virtual Built-In Startup Script: COREMEDIA ”: Starts the JShell and runs startup scripts COREMEDIA only.

$ cm jshell --startup DEFAULT

Example 3.29, “ 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 class-path, which includes the CoreMedia class-path.

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

Example 3.30, “ 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
$ export REPOSITORY_PASSWORD=admin
$ cm jshell

Example 3.31, “ 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.

$ cm jshell

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

jshell> coremedia.connection.getContentRepository()

Example 3.32, “ Connection within JShell ”: If you skipped specifying a connection to connect to at startup, 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.33, “ 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 --no-startup ./mystartup.jsh

Example 3.34, “ 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 afterwards. Specifying --no-startup ensures, that the default COREMEDIA startup script will not be triggered.