2022 June Release

General Use of Fabasoft app.ducxPermanent link for this heading

This chapter focuses on the general use of Fabasoft app.ducx like creating Fabasoft app.ducx projects or working together on a single project.

General Structure of a Fabasoft app.ducx ProjectPermanent link for this heading

A Fabasoft app.ducx project consists of one or more source files, formally known as compilation units, and project files that are specific to the development environment used (Eclipse). The source code for an app.ducx project is typically stored in one or more text files with a file extension of .ducx-om, .ducx-rs, .ducx-uc, .ducx-ui, .ducx-os, .ducx-bp, .ducx-ut, or .ducx-cu.

Each source file contains exactly one model. A model consists of a block that can contain import declarations and element definitions.

The following example illustrates the skeleton of a Fabasoft app.ducx object model source file that contains import declarations and some element definitions.

Example

//=======================================================================
//

// Copyright information

//

//=======================================================================

objmodel APPDUCXSAMPLE@200.200
{
  import COOSYSTEM@1.1;

  class Product : BasicObject {
    mlname;
    string[] productdescription;
    currency unitprice;
  }
}

Note: The encoding of source files in an Fabasoft app.ducx project is UTF-8.

Creating Fabasoft app.ducx Projects Using EclipsePermanent link for this heading

With Eclipse, you can also either create a new Fabasoft app.ducx project from scratch or create a project from an existing software component.

Before creating your first Fabasoft app.ducx project, it is recommended that you define a default web service in the Eclipse preferences.

Fabasoft app.ducx Specific Settings in the Eclipse PreferencesPermanent link for this heading

Fabasoft app.ducx allows you to define several Fabasoft app.ducx-specific settings in the Eclipse preferences dialog box. To configure these settings, click “Preferences“ on the “Window“ menu, and select “Fabasoft app.ducx” in the dialog box (see following figure).

It is recommended that you define a Default Web Service for Fabasoft app.ducx in the Eclipse preferences before you create your first Fabasoft app.ducx project.

In the preferences dialog box, you can also set the threshold for compressed uploads. When running a Fabasoft app.ducx project, a software component is automatically generated from the output of the Fabasoft app.ducx compiler, and uploaded to the development web service. If the file size of the software component to be uploaded exceeds the threshold defined in the Compressed Upload Threshold field, the software component is automatically compressed to minimize the upload time.

You can also activate code signing and customize the colors used for syntax coloring in the preferences dialog box.

Creating a New Fabasoft app.ducx ProjectPermanent link for this heading

On the “File“ menu, point to “New“, and then click “Project“ to invoke the “New Project” dialog box (see following figure). In this dialog box, select “Fabasoft app.ducx Project” from the “Fabasoft app.ducx” folder and click “Next“.

In the “Create a Fabasoft app.ducx project” dialog box (see following figure), enter a Project name for your project.

If you clear the Use default location check box, you can enter a path for your new Fabasoft app.ducx project. Otherwise, the default location defined in the Eclipse preferences is used.

By default, the web service configured in the Eclipse preferences is used for connecting to your development domain. However, you may also define a project-specific web service by clearing the Use default web service check box.

In the Software component field, you have to provide the reference of the software component created for your new Fabasoft  app.ducx project. Additionally, select the domain ID the software component should belong to.

During the development process component objects are created. Each component object gets a unique address that contains a major and minor domain ID and a subsequent number. The domain ID is defined in the license file for Fabasoft app.ducx and cannot be changed.

Note: For cloud app development a range service is provided. More information can be found in the document “Developing Fabasoft Cloud Apps”.

For productive development a personal address range file and an address range has to be entered in the Address file and Address ranges field to ensure unique addresses. Select a start address and an end address. The natural numbers within the range are used for the created component objects. If all addresses are used, an error is generated. In this case an additional range for the Fabasoft app.ducx project has to be provided.

Attention: All addresses have to be world-wide unique. On the one hand this is assured by Fabasoft, providing each major and minor domain ID combination only once. On the other hand, the address ranges have to be managed by the customers themselves. If several developers work within a domain ID, each developer is only allowed to use defined address ranges such that no address can be assigned twice.

The current domain cannot be ranged and must not be used for productive development.

Note: Later on, the address range file and the defined address ranges can be modified in the Fabasoft app.ducx project settings. An address range file can be added or changed and additional address ranges can be defined.

After clicking “Next“, you are taken to the dialog box pictured in the following figure, where you can add software component references to your Fabasoft app.ducx project. For detailed information on software component references, please refer to chapter “Adding a Software Component Reference”.

Click “Next“ for the wizard to take you to the next step, where you need to provide a Name and a Version for your software component along with a Copyright file. Confirm your choices by clicking “Next”.

In the following dialog box, you may select template files that you want the wizard to automatically generate for your Fabasoft app.ducx project. For instance, as your Fabasoft app.ducx project will most likely contain object model elements, you may want to consider checking the .ducx-om template for the wizard to add an object model file to your app.ducx project for you. However, you can also add files to your Fabasoft app.ducx project later.

Click “Finish“ for the wizard to create your new Fabasoft app.ducx project. The Fabasoft app.ducx feature for Eclipse also includes a predefined perspective that is optimized for working with Fabasoft app.ducx. After clicking “Finish“, you are asked whether you want to activate the Fabasoft app.ducx perspective.

Working With Fabasoft app.ducx Projects Using EclipsePermanent link for this heading

This chapter outlines the use of Eclipse when working with Fabasoft app.ducx projects.

Running a Fabasoft app.ducx ProjectPermanent link for this heading

You have to create a new launch configuration before you can run a Fabasoft app.ducx project in Eclipse. To do so, click “Run Configurations“ on the “Run“ menu. This will bring up the dialog box shown in the following figure.

In this dialog box, click the “New launch configuration button and enter a Name for the new launch configuration. In addition to this, select the Project by clicking “Choose”. Click “Apply“ to save your settings, and “Run“ to run the Fabasoft app.ducx project.

Once a Fabasoft app.ducx launch configuration has been created, you can select the existing launch configuration on the “Run as“ menu to run the Fabasoft app.ducx project.

Modified project files may be saved automatically depending on the launch configuration of Eclipse.

Note: A Fabasoft app.ducx project is always compiled for the current version and software edition of the developer domain.

Adding a Software Component ReferencePermanent link for this heading

Whenever you either explicitly or implicitly reuse parts of the functionality provided by another software component, you have to add a reference to this software component.

To add a software component to your Fabasoft app.ducx project in Eclipse, click “Add Reference“ on the “Software Component References“ context menu in the Eclipse Project Explorer. In the dialog box shown in the following figure, select the software component to add. You may also select more than one software component.

Adding a reference to a software component triggers a web service call, which downloads required information about this software component to the local Fabasoft app.ducx cache on your computer. The cached information is then used by the Fabasoft app.ducx compiler and for providing context-sensitive help.

All added software components will be inserted in the list of prerequisite components of the software component when the project is built.

You can also remove references to unused software components at any time.

Adding a Source FilePermanent link for this heading

In Eclipse, you can add new source files to an existing Fabasoft app.ducx project at any time by selecting the type of source file you would like to add from the “New“ context menu of your Fabasoft app.ducx project in the Eclipse Project Explorer (see following figure).

Adding ResourcesPermanent link for this heading

You can add resources – such as symbols – to a Fabasoft app.ducx project. It is recommended to add all resources to the resources folder. Symbols should be added to the symbols subfolder.

In Eclipse, a new symbol can be added to your Fabasoft app.ducx project by clicking “New“ on the context menu of the Eclipse Project Explorer.

To add an existing resource, just drag the file into the desired folder of your Fabasoft app.ducx project. You may also click “Import“ on the context menu of the target folder in the Eclipse Project Explorer.

Managing Address RangesPermanent link for this heading

The address range file and the defined address ranges can be managed in the Fabasoft app.ducx project settings. The used address range file can be selected, new address range files can be created and additional address ranges can get requested.

Note: For access to the configured range service it may be necessary to use an application password.

Attention: Make sure that there is an address range file for every developer working concurrently on the project. Doing so prevents later merging problems.

Managing AddressesPermanent link for this heading

In some rare cases it may be useful to change the automatically assigned object addresses. For this purpose, an object address editor is available. It can be accessed via the “Address Assignment” entry of a project in the Eclipse Project Explorer.

Attention: We recommend changing object addresses only if it is absolutely necessary (e.g. if two developer have accidently used the same address range).

Defining a Friend ComponentPermanent link for this heading

In the Fabasoft app.ducx project settings a list of friend component references can be provided for your component. The friend components will have access to all the private entities of your component.

Steps to make a component APPDUCXSAMPLEFRIEND@200.200 friend of a component APPDUCXSAMPLE@200.200:

  • In the Fabasoft app.ducx project settings of APPDUCXSAMPLE@200.200 add APPDUCXSAMPLEFRIEND@200.200 to the “Friend Components” list.
  • Compile and upload APPDUCXSAMPLE@200.200
  • In project APPDUCXSAMPLEFRIEND@200.200 add or update reference APPDUCXSAMPLE@200.200.

Working Together/Using a Version Control SystemPermanent link for this heading

For Fabasoft app.ducx projects it is also possible to use a version control system like Subversion or Git very easily.

Following files and directories of a Fabasoft app.ducx project have to be checked in:

  • .ranges (folder)
    All files except the .mergedducxranges.xml are required for building your projects.
  • .references (folder)
    Only *.xml (cache, solutions, languages) are required for building your projects. For convenience *.refdoc may be checked in to get quick tips in the editor without updating the references.
  • .references/lib (folder)
    Only those JARs (e.g. AXIS2 runtime JARs) have to be checked in that have references in the .classpath file.
  • .settings (folder)
    The .settings folder contains also developer specific settings for the project (com.fabasoft.ducx.prefs). Do not check in or share com.fabasoft.ducx.prefs but keep it in order to not lose personal settings like the name of the personal address range file.
  • resources (folder)
  • src (folder)
  • .classpath
  • .ducxproject
  • .project
  • *.ducx-*

Note: Some of these directories and files are optional. Some older projects use .ducxranges.* files instead of the .ranges folder. These can be replaced with the range files of the .ranges folder.

Several developers may work on a single project. In a project the address ranges of each developer should be stored in a different file. During development, only the address range file that belongs to the developer gets changed. It is essential to check in the address range file together with the source files.

Customizing Font and ColorsPermanent link for this heading

Fabasoft app.ducx provides customizable font and background color properties for the multilingual strings and address assignment editor,

The font and the background color can be defined in the Eclipse preferences (“Window” > “Preferences” > “General” > “Appearance” > “Colors and Fonts”> “app.ducx”).

The font of the app.ducx language editors can be customized by changing the value of “Text Font” in the Eclipse preferences (“Window” > “Preferences” > “General” > “Appearance” > “Colors and Fonts”> “Basic”).

Submitting Feedback Regarding Fabasoft app.ducxPermanent link for this heading

Fabasoft app. ducx provides a possibility to submit feedback. A button is placed in the main tool bar and with a click on this button you can enter text for your feedback. Additionally, you can specify which projects you want to submit and if you want to include a screenshot.

Prelaunch and Postlaunch ExpressionsPermanent link for this heading

Before and after uploading an app.ducx project, expressions can be executed on the web server. These have to be named prelaunch-ducx.xp and postlaunch.ducx-xp. If such files are present, in the launch configuration, checkboxes to enable the execution of these expressions are enabled.

Note: To be sure that the expression is valid, only use temporary variables.

Updating Fabasoft app.ducx Projects Using EclipsePermanent link for this heading

If existing projects should be compiled for a newer version carry out following steps.

  • Make sure that the development domain and the Fabasoft app.ducx plug-in have been updated.
  • In the “Project Explorer” navigate to the desired project.
  • Open the context menu of the “Software Component References” folder and click “Update All References”.
  • Open the “Project” menu and click “Clean”.

This way you get an overview of all warnings and errors in your project that may arise because of changes in the domain caused by the update.

Build and Test EnvironmentsPermanent link for this heading

In build and test environments it is necessary that Fabasoft app.ducx projects can be compiled and loaded using the command line instead of utilizing the Eclipse environment.

Fabasoft app.ducx supports automatic compiling and loading of Fabasoft app.ducx projects in a domain utilizing Apache Ant. Thus, appropriate tests can be carried out immediately after a successful build.

PrerequisitesPermanent link for this heading

Make sure that Apache Ant is properly installed. For more information about the installation and configuration of Apache Ant consult http://ant.apache.org/manual/index.html.

If problems with the Java heap size arise, the values for the Java heap size have to be adjusted accordingly (e.g. -Xms64m -Xmx1024m). This can be done by setting the ANT_OPTS variable.

  • set ANT_OPTS=-Xms64m -Xmx1024m (Microsoft Windows)
  • export ANT_OPTS="-Xms64m -Xmx1024m" or
    setenv ANT_OPTS "-Xms64m -Xmx1024m" (Linux; depending on the shell)

Environment VariablesPermanent link for this heading

The environment variable DUCX_HOME is used to specify the path to the needed libraries for compiling and loading. The libraries can be found here: https://download.fabasoft.com/updates/update_appducx/ant.zip

At least the environment variable DUCX_HOME must be set. For example, if you copy the Ant directory in the C:\appducxLibraries directory, set DUCX_HOME to C:\appducxLibraries.

The following environment variables may be used in the Fabasoft app.ducx project file. If this is the case, make sure that the environment variables are also set in the build environment or that the corresponding values are defined in the Apache Ant build.xml.

  • Environment variable for the web service configuration (e.g. DUCX_WEBSERVICECONFIGFILE)
    Defines the path to a web service configuration file (.ducxws). This setting is necessary, if component object references should be updated or the project should be loaded in a domain.
    Note: To create a configuration file, edit the properties of a Fabasoft app.ducx project in Eclipse and uncheck Use default web service. Specify the properties of the web service as needed.
  • Environment variable for the copyright file (e.g. DUCX_COPYRIGHT)
    Defines the path to a copyright file of the software component defined by the Fabasoft app.ducx project.
  • Environment variable for the version (e.g. DUCX_VERSION)
    Defines the version of the software component defined by the Fabasoft app.ducx project.
    You are free to use any version number (an integer).
    Fabasoft uses a two-digit schema (e.g. 220400 to denote Version 22.4.0).
  • Environment variable for the target version (e.g. DUCX_TARGET)
    Defines the version of the domain the Fabasoft app.ducx project is compiled for. Available target versions: VERSIONyyx (yy: major version, x: minor version; e.g. VERSION224)

Executing Fabasoft app.ducx Ant TasksPermanent link for this heading

To execute Fabasoft app.ducx Ant tasks you can copy and modify the ant-build-template.xml provided here: https://download.fabasoft.com/updates/update_appducx/ant.zip. Copy the file in a directory and rename the file to build.xml. Modify the build.xml file as described in chapter “Fabasoft app.ducx Ant Tasks” and execute Apache Ant (ant).

AuthenticationPermanent link for this heading

There are two possible ways to authenticate the user.

Basic authentication

With basic authentication, a username password pair is used to authenticate the user.

Basic Authentication Example

<target name="definewebsvc">
  <webservice id="websvc" url="your baseurl" timeout="your timeout">
    <authentication>
      <basic user="your username" password="your password"/>
    </authentication>
  </webservice>
</target>

Client Certificate

With client certificate authentication, a keystore and a truststore have to be supplied to authenticate against a web service.

Client Certificate Example

<target name="definewebsvc">
  <webservice id="websvc" url="your baseurl" timeout="your timeout">
    <authentication>
       <clientcertificate>
         <keystore location="/ssl/keystore.p12" password="xxx" type="pkcs12" />
         <truststore location="/ssl/truststore.jks" password="xxx" type="jks" />
       </clientcertificate>
    </authentication>
  </webservice>
</target>

Fabasoft app.ducx Ant TasksPermanent link for this heading

Fabasoft app.ducx provides the following Ant tasks:

  • updaterefs
    The software component cache gets updated based on the defined web service in the Fabasoft app.ducx project file.
  • clean
    All intermediate files of a previous compilation are deleted.
  • cleanlangfiles
    Cleans up multilingual names and explanation texts not referenced in the source code anymore.
  • compile
    The defined Fabasoft app.ducx project is compiled.
  • load
    The defined Fabasoft app.ducx project is loaded in the domain based on the defined web service in the Fabasoft app.ducx project file.
  • extract
    The defined Fabasoft app.ducx project is extracted in a COO file.
  • extractsolution
    Software products, software editions and software solutions specified in the defined Fabasoft app.ducx project are extracted.
  • startcoverage
    Starts an app.ducx expression coverage session. A coverage session will live as long until it is explicitly stopped. Sessions not stopped at service shutdown will be persisted and restarted at service startup.
  • stopcoverage
    Stops an app.ducx expression coverage session and saves coverage data. For every software component, a coverage data file is provided.
  • mergecoverage
    Merges coverage data from various sources into one overage data file. This task also can create separate expression and object model coverage files.
  • ducxunittest
    Executes the unit tests defined in a given set of components.

The following XML fragment shows the main part of the build.xml file. For each project to be compiled define a ducx tag. Alternatively, you can define one ducx tag with a base folder containing several projects to be compiled. Make sure that the copyright, version and target is specified within the build.xml file or within the .ducxproject file.

It is possible to compile many projects in parallel by specifying a project folder list in the property ducxprojectlist. In this case the property logdir specifies a folder for log output.

Core Example

<target name="definewebsvc">
  <webservice id="websvc" url="your baseurl" timeout="your timeout">
    <authentication>
      <basic user="your username" password="your password"/>
    </authentication>
  </webservice>
</target>

<target name="main" depends="declare, definewebsvc">
  <!-- define a ducx tag for each software component to compile -->
  <ducx ducxproject="d:/projects/Symb/.ducxproject" verbose="false">
    <!-- use the web service with ID "websvc" -->
    <webservice refid="websvc"/>
    <!-- define the tasks to be carried out -->
    <!-- clean up multilingual names and explanation texts -->

    <cleanlangfiles copyright="d:/projects/static/copyright.txt"/>
    <!-- delete intermediate files -->

    <clean/>
    <!-- update cache -->
    <updaterefs/>
    <!-- compile the app.ducx project -->
    <compile
      copyright="d:/projects/static/copyright.txt"
      version="1036"
      target="VERSION1036"
      coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
    <!-- load the app.ducx project in a domain -->
    <load/>
    <!-- extract the app.ducx project to the specified file -->
    <extract target="runtime/symb.coo"/>
    <!-- extract the specified software solution to the target directory -->
    <extractsolution target="runtime" solution="SolutionSymb@200.200"/>
  </ducx>
  <!-- execute only some of the available tasks -->
  <ducx ducxproject="d:/projects/Jmb/.ducxproject" verbose="true">
    <clean/>
    <compile coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
  </ducx>
  <!-- compile all projects in the defined root directory -->
  <ducx root="d:/projs" ducxproject=".ducxproject">
    <clean/>
    <compile coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
  </ducx>
</target>

Parallel Example

<target name="definewebsvc">
  <webservice id="websvc" url="your baseurl" timeout="your timeout">
    <authentication>
      <basic user="your username" password="your password"/>
    </authentication>
  </webservice>
</target>

<target name="main" depends="declare, definewebsvc">
  <!-- define a ducx tag for each software component to compile -->
  <ducx ducxprojectlist="d:/projects/projects.lst"  logdir="d:/projects/logs" verbose="false">
    <!-- use the web service with ID "websvc" -->
    <webservice refid="websvc"/>
    <!-- define the tasks to be carried out -->
    <!-- clean up multilingual names and explanation texts -->

    <cleanlangfiles copyright="d:/projects/static/copyright.txt"/>
    <!-- delete intermediate files -->

    <clean/>
    <!-- update cache -->
    <updaterefs/>
    <!-- compile the app.ducx project -->
    <compile
      copyright="d:/projects/static/copyright.txt"
      version="220400"
      target="VERSION224"

      coodir="d:/projects/coocache"

      cookit="d:/projects/Kit/Setup"

      coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
    <!-- load the app.ducx project in a domain -->
    <load/>
    <!-- extract the app.ducx project to the specified file -->
    <extract target="runtime/symb.coo"/>
    <!-- extract the specified software solution to the target directory -->
    <extractsolution target="runtime" solution="SolutionSymb@200.200"/>
  </ducx>
  <!-- execute only some of the available tasks -->
  <ducx ducxproject="d:/projects/Jmb/.ducxproject" verbose="true">
    <clean/>
    <compile coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
  </ducx>
  <!-- compile all projects in the defined root directory -->
  <ducx root="d:/projs" ducxproject=".ducxproject">
    <clean/>
    <compile coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
  </ducx>
</target>

Single File Mode Example

<target name="main" depends="declare">
  <!-- define a ducx tag for each software component to compile -->
  <ducx ducxproject="d:/projects/Symb/.ducxproject" verbose="false" single="true">
    <!-- update cache -->
    <updaterefs/>
    <!-- delete intermediate files -->
    <clean/>
    <!-- compile the app.ducx project -->
    <compile
      copyright="d:/projects/static/copyright.txt"
      version="1022"
      target="VERSION1022"
      coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
</target>

Coverage Example

<target name="coverage" depends="declare, coverage-start, coverage-play, coverage-stop"/>

<target name="coverage-start">
  <startcoverage session="compliance-session-id" verbose="false">
    <!-- session defines a variable name to write the session id into -->
    <!-- webservice defines connection -->
    <webservice url="your baseurl" timeout="your timeout">
      <authentication>
        <basic user="your user" password="your password"/>
      </authentication>
    </webservice>
    <!-- By defining an Edition all assigned components
         (per Software Component Object or as textual reference)

         will be included in measuring -->
    <cover>your Edition</cover>
      <!-- There can be multiple Entries -->
    <cover>your component</cover>
  </startcoverage>
</target>

<target name="coverage-play">
  <!-- do whatever to produce events to be measured by coverage,
       e.g. launch app.test, evaluate unit tests -->

</target>

<target name="coverage-stop">
  <!-- session is a variable holding a session id from a previous startcoverage task
       target is a directory, where coverage information will be placed in

       split defines the breakdown of the different coverage data into separate files

   -->

  <stopcoverage session="${compliance-session-id}" target="coverage/in" verbose="false"
  
split="true"/>
</target>

<target name="coverage-merge">
  <!-- merge some coverage.xml files into one -->
  <mergecoverage verbose="true"
    target=”coverage/out/coverage.xml"
    targetmodel=" coverage/out/model.xml"
    targetexpr=" coverage/out/expr.xml">
      <fileset dir=" coverage/in">
        <include name="*.xml"/>
      </fileset>
  </mergecoverage>
</target>

Unit Test Example

<target name="main" depends="declare, evaluate-unittests">
<target name="evaluate-unittests" depends="declare">
  <ducxunittest todir="./ducxunitresultdir">
    <!-- enables trace output matching flags and Java Regular Expression -->
    <trace enabled="true" flags="normal, warning, error" clienttimeout="100"
        servertimeout="1000">
      <include>.+unit test.+</include>
    </trace>
    <webservice refid="websvc"/>
    <!-- by defining an Edition all unit tests from the assigned components
         will be executed -->

    <evaluate>your edition</evaluate>
    <!-- there can be multiple entries -->
    <evaluate>your component</evaluate>
    <evaluate>your unit test group</evaluate>
    <evaluate>your unit test</evaluate>
  </ducxunittest>
  <!-- generate a report e.g. JUnit report -->
</target>

Adding Dynamic Contents to the Software ComponentPermanent link for this heading

When a software component is built in the single build mode, additional contents for the software components can be added dynamically without defining them directly in the software component.

To do so, the contents have to be copied in a predefined folder structure in the output folder build.

Following rules are applied in the build process:

  • Files ending with .refdoc in the help folder get CCT_DEVHELP as COOSYSTEM@1.1:compconttype and the prefix help:.
  • Files in a folder OperatingSystem get WSTYPE_OperatingSystem as COOSYSTEM@1.1:compcontwstype, if the type is available in the enumeration COOSYSTEM@1.1:WorkStationType. For example, WINDOWS_X64 becomes WSTYPE_WINDOWS_X64 and get CCT_NORMAL as COOSYSTEM@1.1:compconttype.

Example

...
<target name="main" depends="declare, definewebsvc">
  <property name="project_dir" value="d:/projects/Symb/" />
  <copy file="${source_dir}/winx64.dll" todir="${project_dir}/build/WINDOWS_X64" />
  <copy file="${source_dir}/centos64.so" todir="${project_dir}/build/CENTOS_X64" />
  <copy file="${source_dir}/helpcontent.so" todir="${project_dir}/build/help" />
  <ducx ducxproject="d:/projects/Symb/.ducxproject" verbose="false" single="true">
    <!-- compile the app.ducx project -->
    <compile
      copyright="${project_dir}/copyright.txt"
      version="1227"
      target="VERSION12"
      coolib="${env.DUCX_HOME}/Ant/ducx/coolibj.jar"/>
  </ducx>
</target>

To add other files to the software component the .ducxproject file may contain a declaration within the <ns:SoftwareComponent> tag in the following format:

  • <ns:Content file="..." basename="..." type="..." language="..." />
  • file
    Contains the absolute or relative file path, starting from the .ducxproject directory.
  • basename
    Contains the component content base name.
  • type
    One of the following values: CCT_DEVHELP, CCT_HELP, CCT_NORMAL.
  • language
    One of the following values: LANG_GERMAN, LANG_ENGLISH, ...

Example

...
<ns:SoftwareComponent>
    ...
    <ns:Content
       file="resources/LANG_GERMAN/help-HELPSampleUsrGer.chm"
       basename="help:HELPSampleUsrGer.chm"
       type="CCT_HELP"
       language="LANG_GERMAN"/>
    ...
</ns:SoftwareComponent>

Update app.ducx LibrariesPermanent link for this heading

To update the app.ducx libraries, download the ZIP file from https://download.fabasoft.com/updates/update_appducx/ant.zip. Replace the current libraries from the directory and subdirectories as defined in the environment variable DUCX_HOME and update the build.xml if necessary. For more information about the environment variables see chapter “Environment Variables”.

Productivity Features of Fabasoft app.ducx Using EclipsePermanent link for this heading

Fabbasoft app.ducx provides following productivity features.

Syntax Highlighting

In all editors is syntax highlighting activated. The colors are similar to the JDT Java editor if possible.

Syntax highlighting can be configured here: “Window” > “Preferences” > “Fabasoft app.ducx” > “Syntax Coloring”.

Tooltips

Reference documentation for used references is displayed when hovering over a reference.

Referenced Form Pages in Outline

Form pages that are not directly defined, but referenced from a form definition are displayed in the outline as well. For convenience, another symbol is used to make it easier to distinguish between defined and referenced form pages.

Highlighting of the Current Domain-Specific Language Editor

On the bottom right of the current editor, a symbol of the current domain specific language is shown. This feature requires the Eclipse appearance theme "Classic". This can be set in “Windows” > “Preferences” > “General” > “Appearance”.

Breadcrumb Navigation

All app.ducx editors support breadcrumb navigation. The breadcrumb bases on the current selection or cursor position in the editor.

The breadcrumb is used to navigate to the definition of other objects within the current file or to other files in the same project.

Static Check of Generic Assignments

Generic assignments are checked in a static way. For example, is a property assigned to a class, it will be checked if the property is implemented on the class.

Example

objmodel DUCXSAMPLE@200.300
{
  import COOSYSTEM@1.1;
  import COODESK@1.1;
  import FSCVAPP@1.1001;

  class<ContentObjectClass> MyClass {
    // OK
    classinitcont<contcontent, contextension> = {
      { file("test.txt"), "txt" }
    }
  }
}

objmodel DUCXSAMPLE@200.300
{
  import COOSYSTEM@1.1;
  import COODESK@1.1;
  import FSCVAPP@1.1001;

  class<CompoundObjectClass> MyClass {
    // NOK: classinitcont is not available on CompoundObjectClass
    classinitcont<contcontent, contextension> = {
      { file("test.txt"), "txt" }
    }
  }
}

Data types and assignment are also checked in complex assignments.

The type compatibility of assignment is defined as:

Object Class of the Attribute

Type of the Value

COOSYSTEM@1.1:AttributeIntegerDef

Integer

COOSYSTEM@1.1:AttributeFloatDef

Float

Integer

COOSYSTEM@1.1:AttributeBoolDef

Boolean

COOSYSTEM@1.1:AttributeDateTimeDef

Datetime

COOSYSTEM@1.1:AttributeEnumDef

String constant of the enumeration value (equals the definition of the enumeration type)

Integer

COOSYSTEM@1.1:AttributeStringDef

String

Expression

Integer

Float

COOSYSTEM@1.1:AttributeExpressionDef

String

Expression

COOSYSTEM@1.1:AttributeObjectDef

Object

COOSYSTEM@1.1:AttributeEnumDef

Enum

COOSYSTEM@1.1:AttributeContentDef

Content (“file(...)”)

Expression

String

Navigation Between Errors and Warnings

Following shotrcuts are supported:

  • CTRL + .
    jumps to the next marker in the current editor
  • CTRL + ,
    jumps to the previous marker

The Eclipse configuration of the markers to jump (errors, warnings, information ...) is in “Window” > “Preferences” > “General” > “Editors” > “Text Editors” > “Annotations”.

Linking Between Outline and Editor

The outline of app.ducx editors is extended with the button "Link with Editor". If this button is checked, the selection adapts itself to the cursor position in the editor and vice versa.

Quick Outline

The shortcut CTRL + O opens the "Quick Outline" in the current editor. This outline supports keyboard navigation and contains a quick search for the current source file.

Change References With Refactoring

If a reference needs to be renamed, but the address and the multilingual name must not change, refactoring supports this process.

To refactor, select or click into a reference or a Fabasoft expression variable. Open the context menu and click “Rename Element”. Enter the new name and press Enter to refactor the element. To start the refactoring, the shortcut Alt + Shift + R can be used, too.

To get a preview of the refactored element, click on the arrow down on the right side of the tooltip and open the preview.

Open Declaration

The shortcut F3 is used to open the declaration of the selected object.

Find References

The shortcut CTRL + Shift + G is used to find references to the selected object. The search result is displayed in the Eclipse "Search" view.

Mark Occurrences

"Mark Occurrences" is used to highlight references to the currently selected object. This feature is activated via the following button in the menu bar.

Code Formatting

All app.ducx editors support code formatting via CTRL + Shift + F. This formats indents and line breaks in the current editor.

The line length for inserting line breaks is configured on the editor page in the global preferences.

Color Picker in the Content Assist of the UI Editor

In the layout block of form pages, the content assist can be used to assign a color value. After the syntax fontcolor = the content assist via CTRL + Space provides a color picker for the favored color.

Expression Information in Complex Assignments

The information about available scopes and parameters of the current expression is also shown if the mouse pointer is placed on the expression keyword. This feature enables the scope and parameter information of expressions in complex assignment.

Information About Variables in Expressions

The type and the scope of a variable are displayed in the tooltip of variables in expressions. The type is only displayed if resolvable.

Goto Definition for All Objects

The feature "Goto definition" is available for all objects in all DSLs. Pressing F3 on a name will jump to the definition of this object.

Copy a Reference From the Project Explorer

The project explorer is extended with a context menu "Copy Reference" on the elements to copy the reference of the selected object to the clipboard.

Outline in the Business Process Editor

The outline of the business process editor is improved with a concrete structure of complex process definitions. Process elements like conditions, loops, parallel or sequential blocks are shown within the process definition.

Warning for Missing User Interface Binding at Object Class Declarations

If an object class has no user interface binding, a warning is shown.

Additionally, a quick fix is provided to create the binding either in an existing or in a new file.

Error for Mismatching Component and Model

If the software component of the source file differs to the software component of the project, an error is shown.

Quick Fix to Add a Reference to the Project

If a software component is imported in a source file and it is not in the references of the current project, a quick fix to add the software component to the project is provided.

If this software component is not available in the configured web service or the web service itself is not available, an error message is shown.

Content Assist

Fabasoft app.ducx provides content assist support within expression blocks and domain specific languages. Content assist may be triggered manually with Ctrl + Space. In several situations content assist gets triggered automatically:

  • ::
    accesses the global scope
  • :>
    accesses the local scope
  • @
    accesses the temporary scope
  • #
    retrieves a component object
  • .
    may be followed by a kernel interface method, a property, an action or a use case

Quick Fix for Ambiguous Elements

If short references are ambiguous within the Fabasoft app.ducx project, a “Quick Fix” is provided. You can choose between possible fully qualified references and replace the short reference with the desired fully qualified reference.

If an unknown identifier has been found during the code validation and a corresponding app.ducx construct could be determined app.ducx offers a quick fix to create such an entity.

Folding

Source code blocks starting with defined keywords like class or enum can be folded to get a better overview of the source code.

Automatically Close Brackets

After typing {, [, ( in the source code the corresponding close bracket is automatically created.

Find the Matching Bracket

If the cursor is behind an opening or closing bracket its counterpart is highlighted. This option can be enabled or disabled on the “Fabasoft app.ducx” > ”Preferences” > ”Editor” preference page.

To jump to the counter part of a bracket, put the cursor behind the opening or closing bracket and press Ctrl + Shift + P. The shortcut key options can be changed in the Eclipse preferences (“Window” > “Preferences” > “General” > “Keys” > “Go to matching bracket”).

Tooltips

If you point to a short reference, the corresponding fully qualified reference is displayed as tooltip. A hyperlink allows viewing the properties of the component object with the Fabasoft Web Client.

Tooltips for use cases, actions, functions and kernel interfaces contain the result types.

Edit Component Object Instances Utilizing the Fabasoft Web Client

Instances of component objects like

  • ACL (COOSYSTEM@1.1:AccessControlList),
  • Data Import (Component Object) (FSCCOLD@1.1001:DataImportComponentObject),
  • Active Report (Text) (COOAR@1.1:ActiveReport_Text),
  • Relational Report Definition (Component Object) (FSCRELREP@1.1001:RelRepDefComponentObject) and
  • Web Service Definition (FSCOWS@1.1001:WebServiceDefinition)

can be edited utilizing the Fabasoft Web Client. The instance gets transformed to Fabasoft app.ducx source code that is inserted in your project. Thus, complex compound properties can be edited very efficiently using a graphical user interface.

In the project explorer navigate to the desired instance and execute the context menu command “Edit”. The default web browser is opened and the instance can be edited. Click ”Next” to transform the instance to Fabasoft app.ducx source code or “Cancel” to discard the changes. The context menu command “Synchronize” can be used to transform the current instance of the domain to Fabasoft app.ducx source code.

Note:

  • While editing the component object in the Fabasoft Web Client no editing in Eclipse is possible.
  • Only changes of the opened instance are considered. Changes of objects that are referenced in object pointer properties of the opened instance are not transformed to Fabasoft app.ducx source code.

Templates

Code snippets, so called templates, are provided for most places in all project files. These are available via the content assist.

Templates are marked in the content assist with a green dot.

Spell Checker

For comments a spell checker is provided. The dictionary can be defined in the Eclipse preferences (“Window” > “Preferences” > “General” > “Editors” > “Text Editors” > “Spelling”). Additionally, a user defined dictionary can be provided to be able to add unknown words to this dictionary.

Right-click on a misspelled word denoted by a red underline and click “Quick Fix” (shortcut: Ctrl + 1). You can select a suggestion, add the word to the user dictionary, ignore the word during the current session or disable spell checking.

Fabasoft Reference Documentation

The object model of Fabasoft products is subsumed in the Fabasoft Reference Documentation https://help.developer.fabasoft.com/index.php?topic=doc/Reference-Documentation/index.htm.

The Fabasoft Reference Documentation is also displayed as tooltip in the Eclipse environment.

The manual description is taken from source code comments e.g. for enumeration types, object classes, use cases or properties. When typing /** and pressing Enter parameters of the following use case are inserted automatically for easier documentation.

If a component object reference should be displayed in the “See also” block, the full reference has to be used after the @see tag. Useful references (e.g. type of the parameters, members of an object class...) are generated implicitly.

It is possible to embed code snippets in the comment. These snippets should be surrounded by the tags <expr> and </expr>.

Note: The text may contain XHTML tags for formatting or structuring (e.g. <b></b>, <em></em>, <pre></pre>, <ul></ul>, <ol></ol>, <li></li>, <code></code>, <br/>).

Note: For a complete description of the syntax for writing reference documentation comments refer to http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html.

A description for the software component itself may be defined in the properties of a project (“Properties” > “Fabasoft app.ducx” > “Description file”).

Highlighting Obsolete Symbols

All obsolete symbols are highlighted with strikethrough, this is the same way as deprecated symbols in Java. Please note that using obsolete symbols from other software components results in a compiler warning.

Quick Fix for Type Warnings or Errors

Due to the increased occurrence of invalid type warnings quick fixes for these types of error are supplied. There are two corrections implemented:

  • Use first item
    [0]: fixes a single/multiple value warning
  • Add cast to <type>
    inserts the required type cast

Quick Fix for Missing Parameters

A quick fix for missing parameters in action and application calls is provided.

Kernel Interfaces

All kernel interfaces are known to the compiler and handling is as easy as possible. This includes consideration of parameters and result types in expressions, tooltips, content assist and highlighting.

Customization Projects

By simply checking a checkbox the app.ducx project is turned into a customization project. Such projects do not create software components and component objects. Instead they contain only subtle changes or additions to existing software components.