Package org.opencms.main

Class 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, List, 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 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 Description
      CmsShell​(java.lang.String webInfPath, java.lang.String servletMapping, java.lang.String defaultWebAppName, java.lang.String prompt, java.util.List<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, java.util.List<I_CmsShellCommands> additionalShellCommands, java.io.PrintStream out, java.io.PrintStream err, boolean interactive)
      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​(CmsObject cms, java.lang.String prompt, java.util.List<I_CmsShellCommands> additionalShellCommands, java.io.PrintStream out, java.io.PrintStream err)
      Creates a new CmsShell.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method 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.
      CmsBenchmarkTable getBenchmarkTable()
      Gets the benchmark table for the shell, lazily initializing it if it didn't exist yet.
      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​(java.util.List<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

    • Constructor Detail

      • CmsShell

        public CmsShell​(CmsObject cms,
                java.lang.String prompt,
                java.util.List<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 objects 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,
                java.util.List<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 objects 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,
                java.util.List<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 list of objects 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.

      • getBenchmarkTable

        public CmsBenchmarkTable getBenchmarkTable()
        Gets the benchmark table for the shell, lazily initializing it if it didn't exist yet.
        Returns:
        the benchmark table for the shell.

      • 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​(java.util.List<I_CmsShellCommands> additionalShellCommands,
                      java.io.PrintStream out,
                      java.io.PrintStream err)
        Initializes the CmsShell.

        Parameters:
        additionalShellCommands - optional objects 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