CmsShell (OpenCms Core API, version 11.0.0)

java.lang.Object
- org.opencms.main.CmsShell

```
public class CmsShell
extends java.lang.Object
```
A command line interface to access OpenCms functions which is used for the initial setup and also can be used for scripting access to the OpenCms repository without the Workplace.
The CmsShell has direct access to all methods in the "command objects". Currently the following classes are used as command objects: CmsShellCommands, CmsRequestContext and CmsObject.
It is also possible to add a custom command object when calling the script API, like in CmsShell(String, String, String, String, I_CmsShellCommands, PrintStream, PrintStream, boolean).
Only public methods in the command objects that use supported data types as parameters can be called from the shell. Supported data types are: String, CmsUUID, boolean, int, long, double, float.
If a method name is ambiguous, i.e. the method name with the same number of parameter exist in more then one of the command objects, the method is only executed on the first matching method object.

Since:

6.0.0

See Also:

CmsShellCommands, CmsRequestContext, CmsObject

Field Summary

Fields
Modifier and Type	Field and Description
`protected CmsObject`	`m_cms` The OpenCms context object.
`protected java.io.PrintStream`	`m_err` Stream to write the error messages output to.
`protected int`	`m_errorCode` The code which the process should exit with in case of errors; -1 means exit is not called.
`protected java.io.PrintStream`	`m_out` Stream to write the regular output messages to.
`static java.lang.String`	`SHELL_PARAM_ADDITIONAL_COMMANDS` Prefix for "additional" parameter.
`static java.lang.String`	`SHELL_PARAM_BASE` Prefix for "base" parameter.
`static java.lang.String`	`SHELL_PARAM_DEFAULT_WEB_APP` Prefix for "servletMapping" parameter.
`static java.lang.String`	`SHELL_PARAM_ERROR_CODE` Prefix for errorCode parameter.
`static java.lang.String`	`SHELL_PARAM_JLAN` Command line parameter to prevent disabling of JLAN.
`static java.lang.String`	`SHELL_PARAM_SCRIPT` Prefix for "script" parameter.
`static java.lang.String`	`SHELL_PARAM_SERVLET_MAPPING` Prefix for "servletMapping" parameter.
`static java.lang.ThreadLocal<java.util.ArrayList<CmsShell>>`	`SHELL_STACK` Thread local which stores the currently active shell instance.

Constructor Summary

Constructors
Constructor and Description
`CmsShell(CmsObject cms, java.lang.String prompt, I_CmsShellCommands additionalShellCommands, java.io.PrintStream out, java.io.PrintStream err)` Creates a new CmsShell.
`CmsShell(java.lang.String webInfPath, java.lang.String servletMapping, java.lang.String defaultWebAppName, java.lang.String prompt, I_CmsShellCommands additionalShellCommands)` Creates a new CmsShell using System.out and System.err for output of the messages.
`CmsShell(java.lang.String webInfPath, java.lang.String servletMapping, java.lang.String defaultWebAppName, java.lang.String prompt, I_CmsShellCommands additionalShellCommands, java.io.PrintStream out, java.io.PrintStream err, boolean interactive)` Creates a new CmsShell.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`execute(java.io.InputStream inputStream)` Executes the commands from the given input stream in this shell.
`void`	`execute(java.io.Reader reader)` Executes the commands from the given reader in this shell.
`void`	`execute(java.lang.String commands)` Executes the commands from the given string in this shell.
`void`	`executeCommand(java.lang.String command, java.util.List<java.lang.String> parameters)` Executes a shell command with a list of parameters.
`void`	`exit()` Exits this shell and destroys the OpenCms instance.
`java.io.PrintStream`	`getErr()` Returns the stream this shell writes its error messages to.
`int`	`getErrorCode()` Gets the error code.
`java.util.Locale`	`getLocale()` Private internal helper for localization to the current user's locale within OpenCms.
`CmsMessages`	`getMessages()` Returns the localized messages object for the current user.
`java.io.PrintStream`	`getOut()` Returns the stream this shell writes its regular messages to.
`java.lang.String`	`getPrompt()` Gets the prompt.
`CmsUserSettings`	`getSettings()` Obtain the additional settings related to the current user.
`static CmsShell`	`getTopShell()` Gets the top of thread-local shell stack, or null if it is empty.
`boolean`	`hasEcho()` Returns true if echo mode is on.
`boolean`	`hasReportError()` Checks whether a report error occurred during execution of the last command.
`protected void`	`help(java.lang.String searchString)` Shows the signature of all methods containing the given search String.
`protected CmsUserSettings`	`initSettings()` Initializes the internal `CmsWorkplaceSettings` that contain (amongst other information) important information additional information about the current user (an instance of `CmsUserSettings`).
`void`	`initShell(I_CmsShellCommands additionalShellCommands, java.io.PrintStream out, java.io.PrintStream err)` Initializes the CmsShell.
`boolean`	`isExitCalled()` Returns true if exit was called.
`boolean`	`isInteractive()` If `true` this is an interactive session with a user sitting on a console.
`static boolean`	`isJlanDisabled()` Check if JLAN should be disabled.
`static void`	`main(java.lang.String[] args)` Main program entry point when started via the command line.
`static void`	`popShell()` Removes top of thread-local shell stack.
`void`	`printPrompt()` Prints the shell prompt.
`static void`	`pushShell(CmsShell shell)` Pushes shell instance on thread-local stack.
`protected void`	`setEcho(boolean echo)` Sets the echo status.
`void`	`setInteractive(boolean interactive)` Set `true` if this is an interactive session with a user sitting on a console.
`void`	`setLocale(java.util.Locale locale)` Sets the locale of the current user.
`protected void`	`setPrompt(java.lang.String prompt)` Sets the current shell prompt.
`static void`	`setReportError()` If running in the context of a CmsShell, this method notifies the running shell instance that an error has occured in a report.
`void`	`start(java.io.FileInputStream inputStream)` Deprecated. use `execute(InputStream)` instead
`boolean`	`validateUser(java.lang.String userName, java.lang.String password, CmsRole requiredRole)` Validates the given user and password and checks if the user has the requested role.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - SHELL_PARAM_ADDITIONAL_COMMANDS
```
public static final java.lang.String SHELL_PARAM_ADDITIONAL_COMMANDS
```
    Prefix for "additional" parameter.
    
    See Also:
    
    Constant Field Values
  - SHELL_PARAM_BASE
```
public static final java.lang.String SHELL_PARAM_BASE
```
    Prefix for "base" parameter.
    
    See Also:
    
    Constant Field Values
  - SHELL_PARAM_DEFAULT_WEB_APP
```
public static final java.lang.String SHELL_PARAM_DEFAULT_WEB_APP
```
    Prefix for "servletMapping" parameter.
    
    See Also:
    
    Constant Field Values
  - SHELL_PARAM_ERROR_CODE
```
public static final java.lang.String SHELL_PARAM_ERROR_CODE
```
    Prefix for errorCode parameter.
    
    See Also:
    
    Constant Field Values
  - SHELL_PARAM_JLAN
```
public static final java.lang.String SHELL_PARAM_JLAN
```
    Command line parameter to prevent disabling of JLAN.
    
    See Also:
    
    Constant Field Values
  - SHELL_PARAM_SCRIPT
```
public static final java.lang.String SHELL_PARAM_SCRIPT
```
    Prefix for "script" parameter.
    
    See Also:
    
    Constant Field Values
  - SHELL_PARAM_SERVLET_MAPPING
```
public static final java.lang.String SHELL_PARAM_SERVLET_MAPPING
```
    Prefix for "servletMapping" parameter.
    
    See Also:
    
    Constant Field Values
  - SHELL_STACK
```
public static final java.lang.ThreadLocal<java.util.ArrayList<CmsShell>> SHELL_STACK
```
    Thread local which stores the currently active shell instance.
    We need multiple ones because shell commands may cause another nested shell to be launched (e.g. for module import scripts).
  - m_cms
```
protected CmsObject m_cms
```
    The OpenCms context object.
  - m_err
```
protected java.io.PrintStream m_err
```
    Stream to write the error messages output to.
  - m_errorCode
```
protected int m_errorCode
```
    The code which the process should exit with in case of errors; -1 means exit is not called.
  - m_out
```
protected java.io.PrintStream m_out
```
    Stream to write the regular output messages to.
- Constructor Detail
  - CmsShell
```
public CmsShell(CmsObject cms,
                java.lang.String prompt,
                I_CmsShellCommands additionalShellCommands,
                java.io.PrintStream out,
                java.io.PrintStream err)
```
    Creates a new CmsShell.
    
    Parameters:
    
    cms - the user context to run the shell from
    
    prompt - the prompt format to set
    
    additionalShellCommands - optional object for additional shell commands, or null
    
    out - stream to write the regular output messages to
    
    err - stream to write the error messages output to
  - CmsShell
```
public CmsShell(java.lang.String webInfPath,
                java.lang.String servletMapping,
                java.lang.String defaultWebAppName,
                java.lang.String prompt,
                I_CmsShellCommands additionalShellCommands)
```
    Creates a new CmsShell using System.out and System.err for output of the messages.
    
    Parameters:
    
    webInfPath - the path to the 'WEB-INF' folder of the OpenCms installation
    
    servletMapping - the mapping of the servlet (or null to use the default "/opencms/*")
    
    defaultWebAppName - the name of the default web application (or null to use the default "ROOT")
    
    prompt - the prompt format to set
    
    additionalShellCommands - optional object for additional shell commands, or null
  - CmsShell
```
public CmsShell(java.lang.String webInfPath,
                java.lang.String servletMapping,
                java.lang.String defaultWebAppName,
                java.lang.String prompt,
                I_CmsShellCommands additionalShellCommands,
                java.io.PrintStream out,
                java.io.PrintStream err,
                boolean interactive)
```
    Creates a new CmsShell.
    
    Parameters:
    
    webInfPath - the path to the 'WEB-INF' folder of the OpenCms installation
    
    servletMapping - the mapping of the servlet (or null to use the default "/opencms/*")
    
    defaultWebAppName - the name of the default web application (or null to use the default "ROOT")
    
    prompt - the prompt format to set
    
    additionalShellCommands - optional object for additional shell commands, or null
    
    out - stream to write the regular output messages to
    
    err - stream to write the error messages output to
    
    interactive - if true this is an interactive session with a user sitting on a console
- Method Detail
  - getTopShell
```
public static CmsShell getTopShell()
```
    Gets the top of thread-local shell stack, or null if it is empty.
    
    Returns:
    
    the top of the shell stack
  - isJlanDisabled
```
public static boolean isJlanDisabled()
```
    Check if JLAN should be disabled.
    
    Returns:
    
    true if JLAN should be disabled
  - main
```
public static void main(java.lang.String[] args)
```
    Main program entry point when started via the command line.
    
    Parameters:
    
    args - parameters passed to the application via the command line
  - popShell
```
public static void popShell()
```
    Removes top of thread-local shell stack.
  - pushShell
```
public static void pushShell(CmsShell shell)
```
    Pushes shell instance on thread-local stack.
    
    Parameters:
    
    shell - the shell to push
  - setReportError
```
public static void setReportError()
```
    If running in the context of a CmsShell, this method notifies the running shell instance that an error has occured in a report.
  - execute
```
public void execute(java.io.InputStream inputStream)
```
    Executes the commands from the given input stream in this shell.
    - Commands in the must be separated with a line break '\n'.
    - Only one command per line is allowed.
    - String parameters must be quoted like this: 'string value'.
    Parameters:
    
    inputStream - the input stream from which the commands are read
  - execute
```
public void execute(java.io.Reader reader)
```
    Executes the commands from the given reader in this shell.
    - Commands in the must be separated with a line break '\n'.
    - Only one command per line is allowed.
    - String parameters must be quoted like this: 'string value'.
    Parameters:
    
    reader - the reader from which the commands are read
  - execute
```
public void execute(java.lang.String commands)
```
    Executes the commands from the given string in this shell.
    - Commands in the must be separated with a line break '\n'.
    - Only one command per line is allowed.
    - String parameters must be quoted like this: 'string value'.
    Parameters:
    
    commands - the string from which the commands are read
  - executeCommand
```
public void executeCommand(java.lang.String command,
                           java.util.List<java.lang.String> parameters)
```
    Executes a shell command with a list of parameters.
    
    Parameters:
    
    command - the command to execute
    
    parameters - the list of parameters for the command
  - exit
```
public void exit()
```
    Exits this shell and destroys the OpenCms instance.
  - getErr
```
public java.io.PrintStream getErr()
```
    Returns the stream this shell writes its error messages to.
    
    Returns:
    
    the stream this shell writes its error messages to
  - getErrorCode
```
public int getErrorCode()
```
    Gets the error code.
    
    Returns:
    
    the error code
  - getLocale
```
public java.util.Locale getLocale()
```
    Private internal helper for localization to the current user's locale within OpenCms.
    
    Returns:
    
    the current user's Locale.
  - getMessages
```
public CmsMessages getMessages()
```
    Returns the localized messages object for the current user.
    
    Returns:
    
    the localized messages object for the current user
  - getOut
```
public java.io.PrintStream getOut()
```
    Returns the stream this shell writes its regular messages to.
    
    Returns:
    
    the stream this shell writes its regular messages to
  - getPrompt
```
public java.lang.String getPrompt()
```
    Gets the prompt.
    
    Returns:
    
    the prompt
  - getSettings
```
public CmsUserSettings getSettings()
```
    Obtain the additional settings related to the current user.
    
    Returns:
    
    the additional settings related to the current user.
  - hasEcho
```
public boolean hasEcho()
```
    Returns true if echo mode is on.
    
    Returns:
    
    true if echo mode is on
  - hasReportError
```
public boolean hasReportError()
```
    Checks whether a report error occurred during execution of the last command.
    
    Returns:
    
    true if a report error occurred
  - initShell
```
public void initShell(I_CmsShellCommands additionalShellCommands,
                      java.io.PrintStream out,
                      java.io.PrintStream err)
```
    Initializes the CmsShell.
    
    Parameters:
    
    additionalShellCommands - optional object for additional shell commands, or null
    
    out - stream to write the regular output messages to
    
    err - stream to write the error messages output to
  - isExitCalled
```
public boolean isExitCalled()
```
    Returns true if exit was called.
    
    Returns:
    
    true if exit was called
  - isInteractive
```
public boolean isInteractive()
```
    If true this is an interactive session with a user sitting on a console.
    
    Returns:
    
    true if this is an interactive session with a user sitting on a console
  - printPrompt
```
public void printPrompt()
```
    Prints the shell prompt.
  - setInteractive
```
public void setInteractive(boolean interactive)
```
    Set true if this is an interactive session with a user sitting on a console.
    This controls the output of the prompt and some other info that is valuable on the console, but not required in an automatic session.
    
    Parameters:
    
    interactive - if true this is an interactive session with a user sitting on a console
  - setLocale
```
public void setLocale(java.util.Locale locale)
               throws CmsException
```
    Sets the locale of the current user.
    
    Parameters:
    
    locale - the locale to set
    
    Throws:
    
    CmsException - in case the locale of the current user can not be stored
  - start
```
@Deprecated
public void start(java.io.FileInputStream inputStream)
```
    Deprecated. use execute(InputStream) instead
    
    Reads the given stream and executes the commands in this shell.
    
    Parameters:
    
    inputStream - an input stream from which commands are read
  - validateUser
```
public boolean validateUser(java.lang.String userName,
                            java.lang.String password,
                            CmsRole requiredRole)
```
    Validates the given user and password and checks if the user has the requested role.
    
    Parameters:
    
    userName - the user name
    
    password - the password
    
    requiredRole - the required role
    
    Returns:
    
    true if the user is valid
  - help
```
protected void help(java.lang.String searchString)
```
    Shows the signature of all methods containing the given search String.
    
    Parameters:
    
    searchString - the String to search for in the methods, if null all methods are shown
  - initSettings
```
protected CmsUserSettings initSettings()
```
    Initializes the internal CmsWorkplaceSettings that contain (amongst other information) important information additional information about the current user (an instance of CmsUserSettings).
    This step is performed within the CmsShell constructor directly after switching to run-level 2 and obtaining the CmsObject for the guest user as well as when invoking the CmsShell command login.
    
    Returns:
    
    the user settings for the current user.
  - setEcho
```
protected void setEcho(boolean echo)
```
    Sets the echo status.
    
    Parameters:
    
    echo - the echo status to set
  - setPrompt
```
protected void setPrompt(java.lang.String prompt)
```
    Sets the current shell prompt.
    To set the prompt, the following variables are available:
    $u the current user name
    $s the current site root
    $p the current project name
    
    Parameters:
    
    prompt - the prompt to set

Class CmsShell

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

SHELL_PARAM_ADDITIONAL_COMMANDS

SHELL_PARAM_BASE

SHELL_PARAM_DEFAULT_WEB_APP

SHELL_PARAM_ERROR_CODE

SHELL_PARAM_JLAN

SHELL_PARAM_SCRIPT

SHELL_PARAM_SERVLET_MAPPING

SHELL_STACK

m_cms

m_err

m_errorCode

m_out

Constructor Detail

CmsShell

CmsShell

CmsShell

Method Detail

getTopShell

isJlanDisabled

main

popShell

pushShell

setReportError

execute

execute

execute

executeCommand

exit

getErr

getErrorCode

getLocale

getMessages

getOut

getPrompt

getSettings

hasEcho

hasReportError

initShell

isExitCalled

isInteractive

printPrompt

setInteractive

setLocale

start

validateUser

help

initSettings

setEcho

setPrompt