The OpenCms shell is an executable that allows to interact with OpenCms from the command line. You can also pass a script to the shell that should be executed. Hence, it is the tool to automatize tasks and, for example, execute them within the scope of a larger normal shell script.
1 What's the benefit of an OpenCms shell?
The OpenCms shell is perfect for automatizing tasks. In particular, tasks that include not only OpenCms specific parts, but also "normal" shell commands. You can call the OpenCms shell from a shell script and paste it an OpenCms script that it should execute.
Particular use cases are
- Automatically install extra modules when deploying OpenCms
- Automatically export database data or modules, e.g., for moving the exported data to another server for backup.
The OpenCms shell also supports import and export in clusters.
2 Calling the OpenCms shell
The OpenCms shell is shipped with the standard OpenCms installation. It's the executable class org.opencms.main.CmsShell. To start the shell the scripts
cmsshell.bat(for Windows)cmsshell.sh(for Linux)
that are placed in the folder {webapp home}/WEB-INF should be used to start the shell. They set the correct extra parameters for excuting the Shell and start it.
The OpenCms shell takes several arguments on startup that can also be given to according start scripts.
Arguments for calling the shell
-
-base Set the absolute path to the OpenCms installations base directory, i.e.,
{absolute path to the webapp home}/WEB-INF. If not provided, the path is read from the system propertyuser.dir. The start scripts set this argument automatically.-
-script Provide the path to a OpenCms shell script file. Such a file lists a series of OpenCms shell commands. The commands are all executed when handing the script to shell on startup.
The last command in your OpenCms shell script should bequitorexit, because mixing batch mode and interactive mode is not supported.-
-servletMapping The servlet mapping defined in the
web.xmlof the OpenCms installation. If not given/opencms/*is used as default.-
-defaultWebApp The webapp name of the default webapp as configured for your servlet container. The default value is
ROOT, as it is in a standard Tomcat installation.-
-additional Add additional shell commands by providing the fully qualified name of a class that implements
I_CmsShellCommandsto make all commands defined in that class available in the shell.
3 Working with the OpenCms shell
We describe how to work with the OpenCms shell in the interactive mode, i.e., without passing a script to the shell. But most information are also useful for writing scripts, because in batch mode, the shell starts exactly as in interactive mode - just the the commands you would type in interactive mode are all read from the given script.
When the shell starts it starts a new OpenCms instance and displays some information on the startup process plus help information. When startup is finished, you see a prompt where you can type commands.
The most important information is the help option on commands. You can get the signature of all available methods that make up commands, grouped by the classes that provide the methods, using help *. You can also search for signatures of methods whose name contains a special substring by typing help {string}. This search is not case-sensitive.
Signatures are shown as methodName(arg1,arg2,..,argn). To use the method as command type methodName arg1 arg2 ... argn.
Let's see a very simple use-case of the help function. You want to login to OpenCms, but don't know exactly how. Thus, you search for login commands via help login. The shell will tell you:
Guest@Online:|/>help login
Available methods in org.opencms.main.CmsShellCommands:
* login(String, String)
Available methods in org.opencms.file.CmsObject:
* loginUser(String, String)
* loginUser(String, String, String)You see three available methods that can be used as commands. To get further information on the methods, lookup the JavaDoc of the classes that implement the methods. We assume, we know already, that the login method takes a username and a password. Thus we log in as follows:
Guest@Online:|/>login Admin admin
You are now logged in as user "Admin".
Admin@Online:|/>3.1 Which commands are available?
The available commands are public methods from various classes. But not all public methods make up a command. The methods must have sufficiently simple arguments. That means, all arguments must have a "simple" type.
The types that are supported for command arguments are the arguments parsable via org.opencms.util.CmsDataTypeUtil.isParseable.
By default commands are exposed for methods of the following classes:
You can lookup descriptions of the methods available as commands in the JavaDoc.
Using the argument -additional when calling the OpenCms shell, you can add an extra class for exposing methods. The class must implement I_CmsShellCommands.
Typing help * in the shell, you can always get an overview on the available commands.
4 How does the OpenCms shell work?
When you call the OpenCms shell, a new instance of OpenCms is started. You do not need to have OpenCms already running in your Tomcat (or other servlet container). You do not even need to start the servlet container at all.