documentation/developerManual/toolkitExtension/creating-the-fragment.html - gerrit/www.eclipse.org/jubula - Git at Google

 <html>
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <title>3.3.1. Creating the fragment</title>
 <link rel="stylesheet" type="text/css" href="../../css/style.css">
 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
 <link rel="home" href="../index.html" title="Jubula Developer Manual">
 <link rel="up" href="remoteControlExtension.html" title="3.3. Remote control extension">
 <link rel="prev" href="remoteControlExtension.html" title="3.3. Remote control extension">
 <link rel="next" href="deploying-the-fragment.html" title="3.3.2. Deploying the fragment">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
 <div class="navheader">
 <table width="100%" summary="Navigation header">
 <tr><th colspan="3" align="center">3.3.1. Creating the fragment</th></tr>
 <tr>
 <td width="20%" align="left">
 <a accesskey="p" href="remoteControlExtension.html">Prev</a> </td>
 <th width="60%" align="center">3.3. Remote control extension</th>
 <td width="20%" align="right"> <a accesskey="n" href="deploying-the-fragment.html">Next</a>
 </td>
 </tr>
 </table>
 <hr>
 </div>
 <div xmlns:d="http://docbook.org/ns/docbook" class="breadcrumbs">
 <span class="breadcrumb-link"><a href="../index.html">Jubula Developer Manual</a></span> &gt; <span class="breadcrumb-link"><a href="toolkitExtension.html">Creating toolkit extensions for custom UI widgets</a></span> &gt; <span class="breadcrumb-link"><a href="remoteControlExtension.html">Remote control extension</a></span> &gt; <span class="breadcrumb-node">Creating the fragment</span>
 </div>
 <div class="section">
 <div class="titlepage"><div><div><h3 class="title">
 <a name="creating-the-fragment"></a>3.3.1. Creating the fragment</h3></div></div></div>
 <p>
       The following steps have to be done to extend the remote
       control:
     </p>
 <div class="orderedlist"><ol class="orderedlist" type="1">
 <li class="listitem"><p>
           Reference the zip-file<br xmlns:d="http://docbook.org/ns/docbook">
           <span class="input">development/org.eclipse.jubula.site.zip</span><br xmlns:d="http://docbook.org/ns/docbook">
           as a <span class="strong"><strong>Software Site</strong></span> in your <span class="strong"><strong>Target Platform</strong></span>. Verify while adding the software site, that the check box <span class="strong"><strong>Include required software</strong></span> is not checked. This software site also includes the Java documention of the source code.
         </p></li>
 <li class="listitem"><p>
           Set the installed software site as your target platform.
         </p></li>
 <li class="listitem">
 <p>
           Create a fragment project with one of the following IDs as
           host:
         </p>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 <li class="listitem"><p>
               <span class="input">org.eclipse.jubula.rc.swing</span><br xmlns:d="http://docbook.org/ns/docbook">
               for extending Swing support.
             </p></li>
 <li class="listitem"><p>
               <span class="input">org.eclipse.jubula.rc.swt</span><br xmlns:d="http://docbook.org/ns/docbook">
               for extending SWT support without RCP environment.
             </p></li>
 <li class="listitem"><p>
               <span class="input">org.eclipse.jubula.rc.rcp.swt</span><br xmlns:d="http://docbook.org/ns/docbook">
               for extending SWT support in Eclipse 3.x and 4.x (including compatibility layer).
             </p></li>
 <li class="listitem"><p>
               <span class="input">org.eclipse.jubula.rc.rcp.e3.swt</span><br xmlns:d="http://docbook.org/ns/docbook">
               for extending GEF support in Eclipse 3.x (without compatibility layer).
             </p></li>
 <li class="listitem"><p>
               <span class="input">org.eclipse.jubula.rc.javafx</span><br xmlns:d="http://docbook.org/ns/docbook">
               for extending JavaFX support.
             </p></li>
 </ul></div>
 </li>
 <li class="listitem"><p>
           Write your own adapter and Tester Classes.
         </p></li>
 </ol></div>
 <p xmlns:d="http://docbook.org/ns/docbook"><table>
 <colgroup>
 <col>
 <col>
 </colgroup>
 <tbody><tr>
 <td><img align="bottom" width="100" height="91" src="../images/img2.jpg"></td>
 <td class="topbotline"><span class="strong"><strong>If you are writing an extension for the JavaFX
       toolkit, make sure that your adapter and Tester Classes really
       get compiled with Java 8 and the Bundle-Required Execution Environment
       is also set to Java 8.
     </strong></span></td>
 </tr></tbody>
 </table></p>
 <p>
       Adapters are used for all supported toolkits, i.e. Swing, SWT,
       GEF, RCP and JavaFX. They wrap and specify graphic components in
       a form we need for our Tester Classes. You can write your own
       adapter or reuse our existing adapters. We recommend reusing our
       adapters to take advantage of the already existing code.
     </p>
 <p>
       Before we have a look at the remote control extension examples
       in <a class="xref" href="extensionExamples.html" title="3.4. ITE and remote control extension examples">Section 3.4, &#8220;ITE and remote control extension examples&#8221;</a>, we describe in general how
       to create an adapter and Tester Classes.
     </p>
 <div class="section">
 <div class="titlepage"><div><div><h4 class="title">
 <a name="creating-an-adapter"></a>3.3.1.1. Creating an adapter</h4></div></div></div>
 <p>
         To use an adapter you have to implement the interface
         <span class="input">IAdapterFactory</span>, which is defined in the package named
         <span class="emphasis"><em>org.eclipse.jubula.rc.common.adaptable</em></span>.

         It is necessary that the implementation of this interface resists in a package named
         <span class="emphasis"><em>org.eclipse.jubula.ext.rc.common.adapter</em></span>.
         The package naming is important for the remote control extension, because adapters can only be found if they are located in a package with the mentioned name.
       </p>
 <p>
         In order to support your own components, the targeted type must be an instance of <span class="input">IComponent</span>, which is defined in the package named
         <span class="emphasis"><em>org.eclipse.jubula.rc.common.tester.adapter.interfaces</em></span>.
         This targeted type can be used for text components. If you want to support your own graphical component, you should at least use the interface <span class="input">IWidgetComponent</span> as the targeted type, which is a child of <span class="input">IComponent</span>. Both interfaces are defined in the same package.
       </p>
 <p>
         For Swing, SWT and JavaFX there are also specific implementations of different adapters in the following packages, which can be used for your own component:
         </p>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 <li class="listitem"><p>
                  <span class="emphasis"><em>org.eclipse.jubula.rc.swing.tester.adapter</em></span>
 	           </p></li>
 <li class="listitem"><p>
                  <span class="emphasis"><em>org.eclipse.jubula.rc.swt.tester.adapter</em></span>
                </p></li>
 <li class="listitem"><p>
                  <span class="emphasis"><em>org.eclipse.jubula.rc.javafx.tester.adapter</em></span>
                </p></li>
 </ul></div>
 <p>
       </p>
 <p>
         Now we know how to create an own adapter in general. The next
         step is to implement one or more Tester Class.
       </p>
 </div>
 <div class="section">
 <div class="titlepage"><div><div><h4 class="title">
 <a name="creating-a-tester-class"></a>3.3.1.2. Creating a Tester Class</h4></div></div></div>
 <p>
         The functionally important aspect of a Tester Class is that it
         contains public methods for the test actions, which will
         appear in the client. These methods are linked to testable
         actions within a user-defined ITE toolkit plug-in.
       </p>
 <p>
         Each ITE toolkit extension provides an XML configuration file,
         which defines the available methods with parameters, as well
         as information for string externalization. Reflection is used
         to call these methods. For this reason, the signature of a
         defined method including its name, and the ordered parameter
         types are important for the remote control extension.
       </p>
 <p>
         You can write your own Tester Classes, but if you only want to support a new component with existing actions, you could use one of our existing Tester Classes, which you can find in the package named
         <span class="emphasis"><em>org.eclipse.jubula.rc.common.tester</em></span>.
         For Swing, SWT and JavaFX there are also specific implementations in the following packages:
         </p>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 <li class="listitem"><p>
                  <span class="emphasis"><em>org.eclipse.jubula.rc.swing.tester</em></span>
                </p></li>
 <li class="listitem"><p>
                  <span class="emphasis"><em>org.eclipse.jubula.rc.swt.tester</em></span>
                </p></li>
 <li class="listitem"><p>
                  <span class="emphasis"><em>org.eclipse.jubula.rc.javafx.tester</em></span>
                </p></li>
 </ul></div>
 <p>
       </p>
 <p>
         Please take the following guidelines into consideration for
         creating Tester Classes:
       </p>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
 <li class="listitem"><p>
             The class must not reside within the namespace / package of other classes of the ITE / RC part. If however this should be necessary you can safely use the package prefix <span class="emphasis"><em>org.eclipse.jubula.ext.</em></span>.
           </p></li>
 <li class="listitem"><p>
             The class must be compatible with <span class="emphasis"><em>Java 1.5</em></span>.
           </p></li>
 <li class="listitem">
 <p>
             It must either
           </p>
 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
 <li class="listitem"><p>
                 implement the interface <span class="input">ITester</span> defined in the package named<br xmlns:d="http://docbook.org/ns/docbook">
                 <span class="emphasis"><em>org.eclipse.jubula.rc.common.tester.interfaces</em></span>,
               </p></li>
 <li class="listitem"><p>
                 or extend the abstract class <span class="input">AbstractUITester</span> defined in the package named<br xmlns:d="http://docbook.org/ns/docbook">
                 <span class="emphasis"><em>org.eclipse.jubula.rc.common.tester</em></span>.
               </p></li>
 </ul></div>
 </li>
 <li class="listitem"><p>
             The component must provide
             <span class="strong"><strong>public</strong></span> methods for all
             actions declared by the XML configuration file of the
             corresponding ITE toolkit extension.
           </p></li>
 <li class="listitem"><p>
             Each method that implements an action must throw a
             <span class="input">StepExecutionException</span> defined in the
             package named <span class="emphasis"><em>org.eclipse.jubula.rc.common.exception</em></span>
             to notify the ITE if the execution of the action has failed.
           </p></li>
 </ul></div>
 </div>
 <div class="section">
 <div class="titlepage"><div><div><h4 class="title">
 <a name="creating-an-container-adapter"></a>3.3.1.3. Creating an container adapter</h4></div></div></div>
 <p>
 			This is a JavaFX exclusive way to extend the functionality of Jubula. You
             can use this extension mechanism to make components "mappable" that are
             normally not, e.g. components which are part of the skin of a control.
             With the container extension mechanism you are able to add the possibility
             of mapping such components. But to keep the user experience in the
             object mapping like it is designed, such an extension has to be very
             specific.
 		</p>
 <p>
 			The approach is very similar to creating an adapter. Just create an
             Adapter Factory and an Adapter Class like it is described in the
             corresponding chapter. You have to create this Adapter Class for the type
             of the direct parent node from the component which you wish to map to declare
             it to be a container. For example, if you want to map some content of a cell
             in a ListView, the type would be ListCell.
 			</p>
 <p>
             Additionally, your Adapter Class has to implement the interface
             <span class="emphasis"><em>IContainerAdapter</em></span>. You have to implement the method
             <span class="emphasis"><em>getContent</em></span> and return a list of the components which
             you wish to map.
 		</p>
 </div>
 </div>
 <br xmlns:d="http://docbook.org/ns/docbook"><hr xmlns:d="http://docbook.org/ns/docbook">
 <address xmlns:d="http://docbook.org/ns/docbook">Copyright BREDEX GmbH 2015. Made available under the Eclipse Public License v1.0.</address>
 <br xmlns:d="http://docbook.org/ns/docbook">
 </body>
 </html>
	<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<title>3.3.1. Creating the fragment</title>
	<link rel="stylesheet" type="text/css" href="../../css/style.css">
	<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
	<link rel="home" href="../index.html" title="Jubula Developer Manual">
	<link rel="up" href="remoteControlExtension.html" title="3.3. Remote control extension">
	<link rel="prev" href="remoteControlExtension.html" title="3.3. Remote control extension">
	<link rel="next" href="deploying-the-fragment.html" title="3.3.2. Deploying the fragment">
	</head>
	<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
	<div class="navheader">
	<table width="100%" summary="Navigation header">
	<tr><th colspan="3" align="center">3.3.1. Creating the fragment</th></tr>
	<tr>
	<td width="20%" align="left">
	<a accesskey="p" href="remoteControlExtension.html">Prev</a> </td>
	<th width="60%" align="center">3.3. Remote control extension</th>
	<td width="20%" align="right"> <a accesskey="n" href="deploying-the-fragment.html">Next</a>
	</td>
	</tr>
	</table>
	<hr>
	</div>
	<div xmlns:d="http://docbook.org/ns/docbook" class="breadcrumbs">
	<span class="breadcrumb-link"><a href="../index.html">Jubula Developer Manual</a></span> > <span class="breadcrumb-link"><a href="toolkitExtension.html">Creating toolkit extensions for custom UI widgets</a></span> > <span class="breadcrumb-link"><a href="remoteControlExtension.html">Remote control extension</a></span> > <span class="breadcrumb-node">Creating the fragment</span>
	</div>
	<div class="section">
	<div class="titlepage"><div><div><h3 class="title">
	<a name="creating-the-fragment"></a>3.3.1. Creating the fragment</h3></div></div></div>
	<p>
	The following steps have to be done to extend the remote
	control:
	</p>
	<div class="orderedlist"><ol class="orderedlist" type="1">
	<li class="listitem"><p>
	Reference the zip-file<br xmlns:d="http://docbook.org/ns/docbook">
	<span class="input">development/org.eclipse.jubula.site.zip</span><br xmlns:d="http://docbook.org/ns/docbook">
	as a <span class="strong"><strong>Software Site</strong></span> in your <span class="strong"><strong>Target Platform</strong></span>. Verify while adding the software site, that the check box <span class="strong"><strong>Include required software</strong></span> is not checked. This software site also includes the Java documention of the source code.
	</p></li>
	<li class="listitem"><p>
	Set the installed software site as your target platform.
	</p></li>
	<li class="listitem">
	<p>
	Create a fragment project with one of the following IDs as
	host:
	</p>
	<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
	<li class="listitem"><p>
	<span class="input">org.eclipse.jubula.rc.swing</span><br xmlns:d="http://docbook.org/ns/docbook">
	for extending Swing support.
	</p></li>
	<li class="listitem"><p>
	<span class="input">org.eclipse.jubula.rc.swt</span><br xmlns:d="http://docbook.org/ns/docbook">
	for extending SWT support without RCP environment.
	</p></li>
	<li class="listitem"><p>
	<span class="input">org.eclipse.jubula.rc.rcp.swt</span><br xmlns:d="http://docbook.org/ns/docbook">
	for extending SWT support in Eclipse 3.x and 4.x (including compatibility layer).
	</p></li>
	<li class="listitem"><p>
	<span class="input">org.eclipse.jubula.rc.rcp.e3.swt</span><br xmlns:d="http://docbook.org/ns/docbook">
	for extending GEF support in Eclipse 3.x (without compatibility layer).
	</p></li>
	<li class="listitem"><p>
	<span class="input">org.eclipse.jubula.rc.javafx</span><br xmlns:d="http://docbook.org/ns/docbook">
	for extending JavaFX support.
	</p></li>
	</ul></div>
	</li>
	<li class="listitem"><p>
	Write your own adapter and Tester Classes.
	</p></li>
	</ol></div>
	<p xmlns:d="http://docbook.org/ns/docbook"><table>
	<colgroup>
	<col>
	<col>
	</colgroup>
	<tbody><tr>
	<td><img align="bottom" width="100" height="91" src="../images/img2.jpg"></td>
	<td class="topbotline"><span class="strong"><strong>If you are writing an extension for the JavaFX
	toolkit, make sure that your adapter and Tester Classes really
	get compiled with Java 8 and the Bundle-Required Execution Environment
	is also set to Java 8.
	</strong></span></td>
	</tr></tbody>
	</table></p>
	<p>
	Adapters are used for all supported toolkits, i.e. Swing, SWT,
	GEF, RCP and JavaFX. They wrap and specify graphic components in
	a form we need for our Tester Classes. You can write your own
	adapter or reuse our existing adapters. We recommend reusing our
	adapters to take advantage of the already existing code.
	</p>
	<p>
	Before we have a look at the remote control extension examples
	in <a class="xref" href="extensionExamples.html" title="3.4. ITE and remote control extension examples">Section 3.4, “ITE and remote control extension examples”</a>, we describe in general how
	to create an adapter and Tester Classes.
	</p>
	<div class="section">
	<div class="titlepage"><div><div><h4 class="title">
	<a name="creating-an-adapter"></a>3.3.1.1. Creating an adapter</h4></div></div></div>
	<p>
	To use an adapter you have to implement the interface
	<span class="input">IAdapterFactory</span>, which is defined in the package named
	<span class="emphasis"><em>org.eclipse.jubula.rc.common.adaptable</em></span>.

	It is necessary that the implementation of this interface resists in a package named
	<span class="emphasis"><em>org.eclipse.jubula.ext.rc.common.adapter</em></span>.
	The package naming is important for the remote control extension, because adapters can only be found if they are located in a package with the mentioned name.
	</p>
	<p>
	In order to support your own components, the targeted type must be an instance of <span class="input">IComponent</span>, which is defined in the package named
	<span class="emphasis"><em>org.eclipse.jubula.rc.common.tester.adapter.interfaces</em></span>.
	This targeted type can be used for text components. If you want to support your own graphical component, you should at least use the interface <span class="input">IWidgetComponent</span> as the targeted type, which is a child of <span class="input">IComponent</span>. Both interfaces are defined in the same package.
	</p>
	<p>
	For Swing, SWT and JavaFX there are also specific implementations of different adapters in the following packages, which can be used for your own component:
	</p>
	<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
	<li class="listitem"><p>
	<span class="emphasis"><em>org.eclipse.jubula.rc.swing.tester.adapter</em></span>
	</p></li>
	<li class="listitem"><p>
	<span class="emphasis"><em>org.eclipse.jubula.rc.swt.tester.adapter</em></span>
	</p></li>
	<li class="listitem"><p>
	<span class="emphasis"><em>org.eclipse.jubula.rc.javafx.tester.adapter</em></span>
	</p></li>
	</ul></div>
	<p>
	</p>
	<p>
	Now we know how to create an own adapter in general. The next
	step is to implement one or more Tester Class.
	</p>
	</div>
	<div class="section">
	<div class="titlepage"><div><div><h4 class="title">
	<a name="creating-a-tester-class"></a>3.3.1.2. Creating a Tester Class</h4></div></div></div>
	<p>
	The functionally important aspect of a Tester Class is that it
	contains public methods for the test actions, which will
	appear in the client. These methods are linked to testable
	actions within a user-defined ITE toolkit plug-in.
	</p>
	<p>
	Each ITE toolkit extension provides an XML configuration file,
	which defines the available methods with parameters, as well
	as information for string externalization. Reflection is used
	to call these methods. For this reason, the signature of a
	defined method including its name, and the ordered parameter
	types are important for the remote control extension.
	</p>
	<p>
	You can write your own Tester Classes, but if you only want to support a new component with existing actions, you could use one of our existing Tester Classes, which you can find in the package named
	<span class="emphasis"><em>org.eclipse.jubula.rc.common.tester</em></span>.
	For Swing, SWT and JavaFX there are also specific implementations in the following packages:
	</p>
	<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
	<li class="listitem"><p>
	<span class="emphasis"><em>org.eclipse.jubula.rc.swing.tester</em></span>
	</p></li>
	<li class="listitem"><p>
	<span class="emphasis"><em>org.eclipse.jubula.rc.swt.tester</em></span>
	</p></li>
	<li class="listitem"><p>
	<span class="emphasis"><em>org.eclipse.jubula.rc.javafx.tester</em></span>
	</p></li>
	</ul></div>
	<p>
	</p>
	<p>
	Please take the following guidelines into consideration for
	creating Tester Classes:
	</p>
	<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
	<li class="listitem"><p>
	The class must not reside within the namespace / package of other classes of the ITE / RC part. If however this should be necessary you can safely use the package prefix <span class="emphasis"><em>org.eclipse.jubula.ext.</em></span>.
	</p></li>
	<li class="listitem"><p>
	The class must be compatible with <span class="emphasis"><em>Java 1.5</em></span>.
	</p></li>
	<li class="listitem">
	<p>
	It must either
	</p>
	<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
	<li class="listitem"><p>
	implement the interface <span class="input">ITester</span> defined in the package named<br xmlns:d="http://docbook.org/ns/docbook">
	<span class="emphasis"><em>org.eclipse.jubula.rc.common.tester.interfaces</em></span>,
	</p></li>
	<li class="listitem"><p>
	or extend the abstract class <span class="input">AbstractUITester</span> defined in the package named<br xmlns:d="http://docbook.org/ns/docbook">
	<span class="emphasis"><em>org.eclipse.jubula.rc.common.tester</em></span>.
	</p></li>
	</ul></div>
	</li>
	<li class="listitem"><p>
	The component must provide
	<span class="strong"><strong>public</strong></span> methods for all
	actions declared by the XML configuration file of the
	corresponding ITE toolkit extension.
	</p></li>
	<li class="listitem"><p>
	Each method that implements an action must throw a
	<span class="input">StepExecutionException</span> defined in the
	package named <span class="emphasis"><em>org.eclipse.jubula.rc.common.exception</em></span>
	to notify the ITE if the execution of the action has failed.
	</p></li>
	</ul></div>
	</div>
	<div class="section">
	<div class="titlepage"><div><div><h4 class="title">
	<a name="creating-an-container-adapter"></a>3.3.1.3. Creating an container adapter</h4></div></div></div>
	<p>
	This is a JavaFX exclusive way to extend the functionality of Jubula. You
	can use this extension mechanism to make components "mappable" that are
	normally not, e.g. components which are part of the skin of a control.
	With the container extension mechanism you are able to add the possibility
	of mapping such components. But to keep the user experience in the
	object mapping like it is designed, such an extension has to be very
	specific.
	</p>
	<p>
	The approach is very similar to creating an adapter. Just create an
	Adapter Factory and an Adapter Class like it is described in the
	corresponding chapter. You have to create this Adapter Class for the type
	of the direct parent node from the component which you wish to map to declare
	it to be a container. For example, if you want to map some content of a cell
	in a ListView, the type would be ListCell.
	</p>
	<p>
	Additionally, your Adapter Class has to implement the interface
	<span class="emphasis"><em>IContainerAdapter</em></span>. You have to implement the method
	<span class="emphasis"><em>getContent</em></span> and return a list of the components which
	you wish to map.
	</p>
	</div>
	</div>
	<br xmlns:d="http://docbook.org/ns/docbook"><hr xmlns:d="http://docbook.org/ns/docbook">
	<address xmlns:d="http://docbook.org/ns/docbook">Copyright BREDEX GmbH 2015. Made available under the Eclipse Public License v1.0.</address>
	<br xmlns:d="http://docbook.org/ns/docbook">
	</body>
	</html>