Syntax Checking and the Frank!Doc

Introduction

In this section, you learn how to reach some additional resources that help you to write correct Frank configs. You will gain access to an additional source of documentation, the Frank!Doc, which you can reach through the Frank!Console. Frank configurations are written in XML. They satisfy an XML Schema, the Frank configuration schema, which can be downloaded from the Frank!Console. You will learn how to use this schema when you type your Frank configuration. You will have automatic code completion and tooltips in your text editor.

Preparation

Please do the following preparations:

  1. If you did not do so, set up your Frank2Manual instance of the Frank!Framework as explained in the previous section.

  2. Ensure that you have a file ConfigurationExample1Adapter.xml with the following contents:

    <Module
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="./ibisdoc.xsd">
    <Adapter name="Example1Adapter">
      <Receiver name="Example1Receiver">
        <JavaListener name="Example1" serviceName="Example1"/>
      </Receiver>
      <Pipeline firstPipe="Example">
        <FixedResultPipe name="Example" returnString="Hello World1">
          <Forward name="success" path="EXIT"/>
        </FixedResultPipe>
        <Exit path="EXIT" state="success"/>
      </Pipeline>
    </Adapter>
    </Module>
    

    You should have this file if you successfully followed the instructions of the previous section. You will try syntax checking by editing this file in Visual Studio Code or Eclipse.

Frank configuration schema

Please do the following to download the Frank configuration schema:

  1. Click “Webservices” as shown in the figure below:

    ../_images/webservicesMenu.jpg
  2. Click “IbisDoc”:

    ../_images/webservicesPage.jpg
  3. Right-click “ibisdoc.xsd” (number 1 in the picture below):

    ../_images/ibisDocFiles.jpg
  4. A menu appears that lets you choose what to do with “ibisdoc.xsd”.

  5. Put file ibisdoc.xsd in the same directory as ConfigurationExample1Adapter.xml.

Frank!Doc

From the screen shown at step 3, you can access the Frank!Doc, an additional source of documentation. It lets you search pipes, senders and receivers and it gives you detailed information.

  1. In the picture of step 3, press “The new ibisdoc application” (number 2). The following screen appears:

    ../_images/frankDoc.jpg
  2. As an example, we want to see detailed information about the <FixedResultPipe>. To the top-left, click “Pipes” (number 1). To the bottom-left, all available pipes are listed.

  3. Click “FixedResult” (number 2). To the right, a page with detailed information appears. To the top it confirmst that it is about FixedResult (number 3). You see the attribute you know already, “returnString” (number 4).

  4. Each pipe, sender or receiver corresponds to a Java class in the source code of the Frank!Framework. You can see the Javadoc documentation of this class by clicking “Javadoc” (number 5). This information is written for Java developers, but it may be useful sometimes for Frank developers.

Try code completion

For code completion, you need to configure your text editor. Below, Visual Studio Code and Eclipse are covered.

Visual Studio Code

Please do the following to configure Visual Studio Code for code completion:

  1. Press the plugin menu item (number 1 in the figure below).

    ../_images/visualStudioCodePlugins.jpg
  2. Install the two plugins shown (number 2).

  3. Open ConfigurationExample1Adapter.xml.

  4. Please look at the bottom-right corner. Do you see the following dialog?

    ../_images/vsCodeJava8Required.jpg
  5. If you see this dialog, you have to install the Java Development Kit version 8 as is explained in the following steps. If you do not see the dialog, you can proceed to step 9.

  6. If you already have Java 8, proceed to step 8.

  7. Press the button and follow the instructions to download the Red Hat OpenJDK. Alternatively, you may follow the instructions of https://code.visualstudio.com/docs/java/java-tutorial.

  8. The instructions in the previous step should have asked you to set the JAVA_HOME environment variable. You may have missed that, so we also tell you how to set JAVA_HOME here. Please do the following:

    1. Figure out the path of your java.exe executable. This path should end with \bin\java.exe. Please omit this last part to get the value you need for JAVA_HOME. For example, if the path is C:\Program Files\Java\jdk1.8.0_251\bin\java.exe, then the value you need is C:\Program Files\Java\jdk1.8.0_251. Remember this value.

    2. If you have Windows 10, go to Windows Settings. You should see the page shown below. Type “environment” in the search field (if your Windows language is English) and select “Edit the system environment variables”.

      ../_images/windowsSettings.jpg
    3. You see the dialog shown below.

      ../_images/systemProperties.jpg
    4. Click “Environment Variables…”. You should see the dialog shown below:

      ../_images/environmentVariables.jpg
    5. Select one of the “New…” buttons. You see the dialog shown below:

      ../_images/javaHome.jpg
    6. In the “Variable name” field, fill in JAVA_HOME.

    7. In the “Variable value” field, fill in the value you determined in step a).

    8. Press “OK”. Close all the dialogs by pressing “OK”.

    9. If you are opening Visual Studio Code from a command prompt, please restart that command prompt. Otherwise, your new environment variable is not applied. Also restart Visual Studio Code itself.

  9. After the </Adapter> element close tag, start typing <A. The editor should give you a hint that you mean <Adapter>. You should also see a “i” icon to get more information.

Eclipse

Please do the following to configure Eclipse for code completion:

  1. Open Eclipse and choose the workspace you want.

  2. In the menu, choose File | New | Project… . The New Project dialog appears (number 1 in the figure below):

    ../_images/eclipseNewProject.jpg
  3. Choose “Project” (number 2) and press “Next”.

  4. Enter a project name (number 1 in the figure below). Uncheck “Use default location” (number 2). Browse (number 3) to Frank2Manual. Press “Finish”.

    ../_images/eclipseNewProjectNext.jpg
  5. A new project has appeared in your project explorer (number 1 in the fingure below). You may see a cross before your XML files (number 2). If this is the case, you are using the standard XML editor of Eclipse.

    ../_images/eclipseProjectExplorer.jpg

The standard XML editor of Eclipse may crash if you use it with XML schema ibisdoc.xsd. This XML schema may be too large for the XML editor. You can fix this by installing the Wild Web Developer plugin, which enhances the generic text editor to properly process XML. Please continue as follows:

  1. Update your Eclipse plugins. If you use outdated plugins, your installation may fail.

  2. In the Eclipse main menu, choose Help | Eclipse Marketplace… . The dialog shown below opens.

    ../_images/installWWD.jpg
  3. You see your are in the right dialog (number 1). Type wild web developer in the search field (number 2).

  4. You should see the plugin in the search results (number 3). Press “install” (number 4).

  5. Follow the dialog to do the installation.

  6. Restart Eclipse.

  7. In the Eclipse main menu, choose Window | Preferences.

  8. You can see you are in the Preferences dialog (number 1). Go to “File Associations” (number 4). You find it under “General” (number 2) and “Editors” (number 3).

    ../_images/goToFileAssociations.jpg
  9. You can verify you have the right screen (number 1 in the figure below). Here you can link file types to editors provided by Eclipse. Go to “*.xml” (number 2). If you do not see it, you can use the “Add…” button (number 3).

    ../_images/fileAssociationsFileTypes.jpg
  10. Make the “Generic Text Editor” (number 1 in the figure below) the default using the button (number 2).

    ../_images/chooseDefaultEditor.jpg
  11. Restart Eclipse.

  12. In your project explorer, you see that the new editor is used for your XML files, see below:

    ../_images/verificationNewEditor.jpg
  13. You can see what editor is being used in an editor tab, see below. To use the newly chosen text editor, you have to close all your open XML files and reopen them again.

    ../_images/oldEclipseEditor.jpg
  14. Open “ConfigurationExample1Adapter.xml”.

  15. After the </Adapter> closing tag, please start typing <Ad. Eclipse should present a hint that you mean <Adapter>.