~~
~~ Licensed to the Apache Software Foundation (ASF) under one or more
~~  contributor license agreements.  See the NOTICE file distributed with
~~  this work for additional information regarding copyright ownership.
~~  The ASF licenses this file to You under the Apache License, Version 2.0
~~  (the "License"); you may not use this file except in compliance with
~~  the License.  You may obtain a copy of the License at
~~
~~      http://www.apache.org/licenses/LICENSE-2.0
~~
~~  Unless required by applicable law or agreed to in writing, software
~~  distributed under the License is distributed on an "AS IS" BASIS,
~~  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~~  See the License for the specific language governing permissions and
~~  limitations under the License.
~~
~~

 --------
Apache Commons Exec - Building the command line
 --------
 --------
20 August 2010
 --------

Building the command line

You have two ways to create the command line to be executed

  * parsing the entire command line string
  
  * building the command line incrementally

* General Considerations

  No matter which approach you are using commons-exec does change your command
  line arguments in the following two cases

    * when the executable contains forward or backward slashes

    * when a command line argument contains an unquoted string 

  The following executable arguments

----------------------------------------
./bin/vim
----------------------------------------

  will be translated under Windows to

----------------------------------------
.\\bin\\vim
----------------------------------------

* Parsing the entire command line string

  Parsing the command line string is easy to use but you might run into
  problems when tackling complex scenarios. Therefore this functionality
  was deprecated in the {{{http://ant.apache.org/manual/Tasks/exec.html}Ant Exec task}}.

  Let's have a look at few examples you would like to stick to parsing entire command
  line strings

** Spaces in command line arguments

  Here we would like to invoke a batch file which contains spaces in the path

----------------------------------------
cmd.exe /C c:\was51\Web Sphere\AppServer\bin\versionInfo.bat
----------------------------------------

  Due to the space in the file name we have to quote the file name either with
  single or double quotes otherwise it falls apart into two command line
  arguments <c:\was51\Web> and <Sphere\AppServer\bin\versionInfo.bat>.

----------------------------------------
String line = "cmd.exe /C 'c:\\was51\\Web Sphere\\AppServer\\bin\\versionInfo.bat'";
----------------------------------------

* Building the Command Line Incrementally

  This is the recommended approach and caters also for pre-quoted command
  line argument.

** A simple example

  Now we would like to build the following command line

----------------------------------------
runMemorySud.cmd 10 30 -XX:+UseParallelGC -XX:ParallelGCThreads=2
----------------------------------------

  using the following code snippet
  
----------------------------------------
CommandLine cmdl = new CommandLine("runMemorySud.cmd");
cmdl.addArgument("10");
cmdl.addArgument("30");
cmdl.addArgument("-XX:+UseParallelGC");
cmdl.addArgument("-XX:ParallelGCThreads=2");
----------------------------------------

** A complex example

  Now let's have a look at the following command line found somewhere in the
  internet

----------------------------------------
dotnetfx.exe /q:a /c:"install.exe /l ""\Documents and Settings\myusername\Local Settings\Temp\netfx.log"" /q"
----------------------------------------

  The following code snippet builds the command line using pre-quoted
  arguments and variable expansion

----------------------------------------
File file = new File("/Documents and Settings/myusername/Local Settings/Temp/netfx.log");
Map map = new HashMap();
map.put("FILE", file);

cmdl = new CommandLine("dotnetfx.exe");
cmdl.setSubstitutionMap(map);
cmdl.addArgument("/q:a", false);
cmdl.addArgument("/c:\"install.exe /l \"\"${FILE}\"\" /q\"", false);
----------------------------------------

* For the Desperate

  When crafting a command line it would be really helpful to see what
  happens to your command line arguments. The following scripts can be
  invoked to print your command line arguments for Unix

----------------------------------------
while [ $# -gt 0 ]
do
    echo "$1"
    shift
done
----------------------------------------

  and for Windows

----------------------------------------
:Loop
IF [%1]==[] GOTO Continue
    @ECHO "%1"
SHIFT
GOTO Loop
:Continue
----------------------------------------