blob: 17fb73f6902c99959e1820d0059cb8afc79b5f79 [file] [log] [blame]
<!DOCTYPE html>
<head>
<title>RCPTT Documentation Center</title>
<meta charset="UTF-8">
<link rel="stylesheet" href="https://www.eclipse.org/rcptt/shared/css/bootstrap.min.css">
<link rel="stylesheet" href="https://www.eclipse.org/rcptt/shared/css/main.css">
<link rel="stylesheet" href="https://www.eclipse.org/rcptt/shared/css/prism.css">
<link rel="icon" href="https://www.eclipse.org/rcptt/shared/img/favicon.ico">
<script src="https://www.eclipse.org/rcptt/shared/js/jquery.min.js"></script>
<script src="https://www.eclipse.org/rcptt/shared/js/bootstrap.min.js"></script>
<script src="https://www.eclipse.org/rcptt/shared/js/prism.js"></script>
<script src="https://www.eclipse.org/rcptt/shared/js/ecl.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-39589807-5', 'eclipse.org');
ga('send', 'pageview');
</script>
</head>
<body>
<div id="before-footer">
<header>
<nav class="navbar navbar-default navbar-static-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<span class="navbar-brand">RCPTT Documentation Center</span>
</div>
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav">
<li class="active" >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/getstarted">User Guide</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/faq/">FAQ</a>
</li>
<li>
<a href="http://eclipse.org/rcptt">Back to RCPTT Main Site</a>
</li>
<li>
<a href="http://eclipse.org">Eclipse.org</a>
</li>
</ul>
</div>
</nav>
</header>
<section class="content">
<div class="container">
<div class="row">
<div class="col-sm-3">
<div class="rcptt-sidebar">
<ul class="nav">
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/getstarted/">Get Started</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/testeditor/">Test Case Editor</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/controlpanel">Control Panel</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/assertions/">Assertions</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/ecl/">Eclipse Command Language</a>
<ul class="nav">
<li class="active" >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/ecl/new-command-guide/">New ECL Command Guide</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/ecl/excel-import-export/">ECL commands for Excel import and export</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/ecl/xml-import-export/">ECL commands for XML import and export</a>
</li>
</ul>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/">Contexts</a>
<ul class="nav">
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/workspace/">Workspace</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/workbench/">Workbench</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/launch/">Launch</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/preferences/">Preferences</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/parameters/">Parameters</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/group/">Group</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/folder/">Folder</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/default/">Default</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/super/">Super</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/contexts/ecl/">ECL Script</a>
</li>
</ul>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/verifications/">Verifications</a>
<ul class="nav">
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/verifications/text/">Text</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/verifications/treetable/">Table/Tree</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/verifications/errorlog/">Error Log</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/verifications/time/">Time</a>
</li>
</ul>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/procedures/">Procedures and Variables</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/runner/">Test Runner</a>
<ul class="nav">
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/runner/arguments/">Arguments</a>
</li>
</ul>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/maven/">Maven plugin</a>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/">RAP</a>
<ul class="nav">
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/install/">Install instructions</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/recordReplay/">Record and Replay</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/capability/">Capability Contexts</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/rap-commands/">ECL commands</a>
</li>
<li >
<a href="https://www.eclipse.org/rcptt/documentation/userguide/rap/rap-maven/">Maven plugin</a>
</li>
</ul>
</li>
<li ><a href="https://www.eclipse.org/rcptt/documentation/userguide/integration/test-rail-integration/">Integration with TestRail</a>
</li>
</ul>
</div>
</div>
<div class="col-sm-9">
<h1>New Command Guide</h1>
<p></p>
<p>In this guide we show different ways of extending an existing ECL commands functionality, such as:</p>
<ul>
<li>Retrieve an existing method of Java Object with <b>get-object | invoke</b> commands</li>
<li>Create static methods and use it with <b>invoke-static</b> command</li>
<li>Create your own custom ECL command</li>
</ul>
<h2>Use <i>invoke</i> command to call an existing method of Java object.</h2>
<p>Let's say we need to resize a window with given width and height. There is now such a command in ECL script,
but we know that there is a corresponding <b><i>setSize(int width, int height)</i></b> method for Window Object.</p>
<p>So using <a href="http://download.eclipse.org/rcptt/release/1.5.4/doc/ecl/index.html#get-object">get-object</a> and <a href="http://download.eclipse.org/rcptt/release/1.5.4/doc/ecl/index.html#invoke">invoke</a> ECL commands we can call this method:</p>
<div class="panel panel-default">
<div class="panel-body">
<div class="screenshot">
<img src="https://www.eclipse.org/rcptt/shared/img/screenshot-invoke-1.png"></img>
</div>
</div>
</div>
<p>You can define <a href ="https://www.eclipse.org/rcptt/userguide/procedures">ECL procedure</a>, to make it more convenient:</p>
<div class="panel panel-default">
<div class="panel-body">
<div class="screenshot">
<img src="https://www.eclipse.org/rcptt/shared/img/screenshot-invoke-2.png"></img>
</div>
</div>
</div>
<h2>Create your own custom ECL command</h2>
<p>We are going to show how to create custom ECL commands. As an example we create two ECL commands for Eclipse Views.
First one will show us all registered views in our Eclipse. And the second one will open specified view by ID.</p>
<h3>Import RCPTT sources plugins</h3>
<p>First of all you need to import RCPTT sources plugins from <a href="http://git.eclipse.org/c/rcptt/org.eclipse.rcptt.git/">RCPTT Git repository</a></p>
<h3>Create Plug-in Project</h3>
<p>First of all we'll create new plugin project for our ECL commands called <b>org.eclipse.rcptt.ecl.example.view</b>.
You can use any existing plug-in as well.</p>
<div class="screenshot">
<img src="https://www.eclipse.org/rcptt/shared/img/screenshot-new-command-guide-1.png"></img>
</div>
<h3>Define EMF model for ECL command</h3>
<p>We need to create two EMF classes to show registered plugins with ECL:</p>
<ul><li><b>ShowViews</b> which will be used as an ECL command. This EClass should extend <b>Command</b> EClass from the <b>org.eclipse.rcptt.ecl.core/model/ecl.ecore</b> package</li>
<li><b>View</b> which will be used to store view details. It should contains three string properties: id, label and description.</li>
</ul>
<div class="screenshot">
<img src="https://www.eclipse.org/rcptt/shared/img/screenshot-new-command-guide-4.png"></img>
</div>
<p>If you're not experienced EMF user you can find detailed instruction on the <a href="https://www.eclipse.org/rcptt/documentation/userguide/ecl/define-emf-model/">Define EMF model for ShowViews command</a> page.</p>
<h3>Implement ShowViews command</h3>
<p>Now we need to implement ECL command. Make sure you have all necessary dependencies:</p>
<div class="screenshot">
<img src="https://www.eclipse.org/rcptt/shared/img/screenshot-new-command-guide-7.png"></img>
</div>
<h4>Implement ICommandService interface</h4>
<p>Add new class <b>ShowViewsService</b> which implements <b>org.eclipse.rcptt.ecl.runtime.ICommandService</b> interface as shown below:</p>
<pre>
public class ShowViewsService implements ICommandService {
@Override
public IStatus service(Command command, IProcess context) throws InterruptedException, CoreException {
final IWorkbench workbench = PlatformUI.getWorkbench();
final List<View> views = new ArrayList<View>();
workbench.getDisplay().syncExec(new Runnable() {
@Override
public void run() {
for (IViewDescriptor descriptor : workbench.getViewRegistry().getViews()) {
View view = ViewFactory.eINSTANCE.createView();
view.setId(descriptor.getId());
view.setLabel(descriptor.getLabel());
view.setDescription(descriptor.getLabel());
views.add(view);
}
}
});
IPipe output = context.getOutput();
for (View view : views) {
output.write(view);
}
return Status.OK_STATUS;
}
}</pre>
<p>As you can see the implementation is very simple. We use platform <b>IViewRegistry</b> to collect details of Eclise Views and store this information using EMF View objects.
Then we write collected information to the output pipe. Note that view service will be executed using Eclipse Jobs, so we use Workbench Display to access view info in the UI thread.</p>
<h4>Register ECL command implementation</h4>
<p>Finally we need to register our service using <b>org.eclipse.rcptt.ecl.core.scriptlet</b> extension point:</p>
<div class="screenshot">
<img src="https://www.eclipse.org/rcptt/shared/img/screenshot-new-command-guide-8.png"></img>
</div>
<ul>
<li><b>name</b> - name of the EClass which we use for ECL command</li>
<li><b>namespace</b> - EMF Package URI</li>
<li><b>class</b> - command implementation class. Should implement <b>ICommandService</b> interface</li>
</ul>
<p>By default name of the command EClass will be transformed to the ECL command name. For example, in our case commands will be named show-views.
However you can override this name using <b>friendly_name</b> part of the <b>org.eclipse.rcptt.ecl.core.scriptlet</b> extension point.</p>
<h3>Use show-views command</h3>
<ul>
<li>Let's start new Eclipse instance with the following plugins installed:</li>
<ul>
<li><b>org.eclipse.rcptt.ecl.example.view</b></li>
<li><b>org.eclipse.rcptt.ecl.core</b></li>
<li><b>org.eclipse.rcptt.ecl.parser</b></li>
<li><b>org.eclipse.rcptt.ecl.shell</b></li>
<li><b>org.eclipse.rcptt.ecl.telnet.server</b></li>
<li><b>org.eclipse.rcptt.ecl.telnet.server.ui</b></li>
<li><b>org.eclipse.rcptt.tesla.jface.fragment</b></li>
<li><b>org.eclipse.rcptt.tesla.swt.fragment</b></li>
</ul>
<li>Connect to the ECL telnet server started in this Eclipse (on the 2323 port by default) using any telnet client</li>
<li>Enter show-views command</li>
<li>As a result of your command you will see something like this:</li>
</ul>
<div class="screenshot">
<img src="https://www.eclipse.org/rcptt/shared/img/screenshot-new-command-guide-12.png"></img>
</div>
<h3>Add show-view command</h3>
<p>In the previous sections we discussed how to collect information from Eclipse using ECL.
Now let's add another command which will open some view by id.</p>
<h4>Add ShowView EClass</h4>
<p>Create one more EClass called <b>ShowView</b> with one string field <b>id</b>. This is ECL command and should
extend <b>Command</b> EClass.</p>
<div class="screenshot">
<img src="https://www.eclipse.org/rcptt/shared/img/screenshot-new-command-guide-10.png"></img>
</div>
<h4>Implement ShowView command</h4>
<p>Add <b>ShowViewService</b> java class:</p>
<pre>
public class ShowViewService implements ICommandService {
@Override
public IStatus service(Command command, IProcess context) throws InterruptedException, CoreException {
ShowView view = (ShowView) command;
final String id = view.getId();
PlatformUI.getWorkbench().getDisplay().syncExec(new Runnable() {
@Override
public void run() {
try {
PlatformUI.getWorkbench().getActiveWorkbenchWindow().getActivePage().showView(id);
} catch (PartInitException e) {
throw new RuntimeException(e.getMessage(), e);
}
}
});
return Status.OK_STATUS;
}
}
</pre>
<p>We added this service specially for ShowView command, so we can freely cast specified command to ShowView interface.
This allows us to get id of the view we need to open. Next we use Eclipse Platform API to open view by id in the UI thread.</p>
<h4>Register ShowView command</h4>
<p>Finally we need to register new command through <b>org.eclipse.rcptt.ecl.core.scriptlet</b> extension point:</p>
<div class="screenshot">
<img src="https://www.eclipse.org/rcptt/shared/img/screenshot-new-command-guide-9.png"></img>
</div>
<h4>Use show-view command</h4>
<p>Now we can run our plugin and open necessary view by id:</p>
<div class="screenshot">
<img src="https://www.eclipse.org/rcptt/shared/img/screenshot-new-command-guide-13.png"></img>
</div>
<p><br>
By the way, you can use <b>show-views</b> command to find id of a view you want to open.</p>
<div class="panel panel-danger">
<div class="panel-heading">Important!</div>
<div class="panel-body">
Please note that to make your new custom command work you need to include a plugin with your custom command into your AUT configuration.
</div>
</div>
</div>
</div>
</div>
</section>
<script src="https://www.eclipse.org/rcptt/shared/js/main.js"></script>
</body>