Capella/Tutorials/Extensibility/Command Line

Command Line

Command Line

Capella provides a command line functionality. This functionality helps users to launch some Capella commands from a shell or a build engine as Hudson or Jenkins.

The set of command proposals can be extended with additional specific commands that can be contributed through an extension point.

Extension Point Description

An Eclipse extension point allows plug-ins to contribute constraints into the Capella Command Line framework..

The extension point is provided by:

• the plug-in org.polarsys.capella.core.commandline.core
• and its identifier commandline.

Here is an example of contribution declaration (see in plugin.xml file):

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
   <extension point="org.polarsys.capella.core.commandline.core.commandline">
      <CommandlineExtension
         class=""
         id="">
      </CommandlineExtension>
   </extension>
</plugin>

Each contribution shall provide a class that implements the interface org.polarsys.capelle.core.commandline.core.ICommandLine :

/**
 * Interface for Capella Command Line application.
 * The interface services will be called by the framework in the following order:
 * <ol>
 * <li>{@link #parseContext(IApplicationContext)}</li>
 * <li>{@link #checkArgs(IApplicationContext)}</i>
 * <li>{@link #prepare(IApplicationContext)}</li>
 * <li>{@link #execute(IApplicationContext)}</li>
 * </ol>
 */
public interface ICommandLine {
  /**
   * prints user help
   * (i.e. explains the parameters semantics)
   */
  void printHelp();

  /**
   * called first to get command line arguments
   * @param context
   * @throws CommandLineException
   */
  void parseContext(IApplicationContext context) throws CommandLineException;

  /**
   * checks arguments validity
   * @param context
   * @throws CommandLineException
   */
  void checkArgs(IApplicationContext context) throws CommandLineException;

  /**
   * Prepares the execution
   * (e.g. import projects into the workspace before a document generation)
   * @param context
   * @throws CommandLineException
   */
  void prepare(IApplicationContext context) throws CommandLineException;

  /**
   * Performs the actual work of the command line application
   * @param context
   * @return true if succeeded, false otherwise
   * @throws CommandLineException
   */
  boolean execute(IApplicationContext context) throws CommandLineException;
}

The contributed class can also extends the class org.polarsys.capella.core.commandline.core.AbstractCommandLine, that provides some facilities to manage commands :

public class SampleCommandLine extends AbstractCommandLine {
  /**
   * {@inheritDoc}
   */
  @Override
  public boolean execute(IApplicationContext context) throws CommandLineException {
    
    // Insert your code here

    return true;
  }

  /**
   * {@inheritDoc}
   */
  @Override
  public void checkArgs(IApplicationContext context) throws CommandLineException {
    // check nothing
  }
}

Commands using

The usual way to launch a command line action is the following :

eclipse.exe [-nosplash] [-data <workspace path>] -application <application id> -appid <action id> [-logfile <log file path>] -filepath <capella project name>/<aird file path> [-forceoutputfoldercreation] -outputfolder <output project name>[/<ouput folder name>]

The following list gives the standard usual arguments, shared by all the contributors :

eclipse.exe	mandatory	Capella executable file
-nosplash	optional	Launch Capella without the initial splash screen
-consoleLog	optional	Allows to log messages into the console output
-data	optional	Defines the path to the workspace
-application	mandatory	This identifier is used to launch a specific eclipse application. In the specific case of Capella command line, the required id is org.polarsys.capella.core.commandline.core
-appid	mandatory	This identifier is used to launch a specific command line action
-logfile	optional	The file path to the log file
-filepath	mandatory	Workspace relative path to the model
-forceoutputfoldercreation	optional	Allows to create automatically a folder when it does not exist yet
-outputfolder	mandatory	The project where the action will generate its results. A sub folder is allowed, but optional (and must be unique: sub-sub-folders are not supported)
-import	optional	Defines a list of projects to import into the workspace before doing the actual action. List of projects is a | separated list
-help	optional	Prints the help message

Please refer to Capella embedded documentation (Help > Capella Guide > User Manual > Command Line Support) to get more information about specific use cases.