Altova MapForce Server 2023 Advanced Edition

The following example illustrates how to run a mapping execution file (.mfx) from Java code. On Windows, all the example files are available at the following path: C:\Program Files\Altova\MapForceServer2023\etc\Examples. They are as follows:

 

TokenizeString.mfx - A MapForce Server execution file that will be run by the Java program.

AltovaTools.xml - An XML file that provides input data to the mapping program.

 

On Linux and Mac platforms, no examples are pre-installed; however, you can prepare an executable .mfx file like the one run in this example as follows:

 

1.Open the desired mapping design file (.mfd) with MapForce on Windows.

2.On the File menu, select Mapping Settings, and clear the Make paths absolute in generated code check box if it is selected.

3.For each mapping component, open the Properties dialog box (by double-clicking the component's title bar, for example), and change all file paths from absolute to relative. Also, select the Save all file paths relative to MFD file check box. For convenience, you can copy all input files and schemas in the same folder as the mapping itself, and reference them just by the file name. Refer to MapForce documentation for more information about dealing with relative and absolute paths while designing mappings.

4.On the File menu, select Compile to MapForce Server Execution file. This generates the .mfx file that you will subsequently run with MapForce Server, as shown in the code listing below.

 

Prerequisites

Before running the code below, ensure the following prerequisites are met:

 

MapForce Server is installed and licensed

The Java CLASSPATH includes a reference to the MapForceServer.jar library (for an example, see About the Java Interface).

 

If you are using a custom .mfx file as shown above, there may be other prerequisites, depending on the kind of data processed by the mapping. For more information, see Preparing Mappings for Server Execution.

 

On Windows, the example Java project is in the "Program Files" directory, which requires administrative rights. You will either need to run your Java development environment (for example, Eclipse) as administrator, or copy the example to a different folder where you don't need administrative rights.

 

Running the Java program

The code listing below first creates a MapForce Server object. Next, it sets the working directory where the application should look for any files that act as input to the mapping, and where it should generate the mapping output files. As mentioned above, the example mapping file reads data from a source XML file—so make sure that both the XML file and its schema exist in the working directory.

 

The setServerPath method specifies the path to the MapForce Server executable. For example, on Ubuntu, this would be /opt/Altova/MapForceServer2023/bin/mapforceserver. You can omit the setServerPath if you did not move the MapForceServer.jar from its default location.

 

Finally, the run method runs a mapping (.mfx file) that was compiled with MapForce (for example, TokenizeString.mfx). On success, the program below generates a CSV file and an XML file in the working directory, as well as output text on the command line. On error, the program attempts to print out the last execution message generated by MapForce Server.

 

import com.altova.mapforceserver.MapForceServer;

 

public class Program {

 

      public static void main(String[] args)

      {

             MapForceServer objMFS;

             try

             {

             // set up the server

                objMFS = new MapForceServer();

             

             // The default location of the server is the directory that the java native library is in.

             // With the following line you could select a different server binary.

             // objMFS.setServerPath(strServerPath);

 

             // The sample data is located in the parent folder of the Java sample code

                objMFS.setWorkingDirectory("..");

 

                System.out.println("Running " + objMFS.getProductNameAndVersion());

 

           //Set global resource file and configuration, if your mapping uses global resources

           //objMFS.setOption( "globalresourcefile", "GlobalResources.xml" ); // "gr" can be used as short name for "globalresourcefile"

           //objMFS.setOption( "globalresourceconfig", "Default" ); // "gc" can be used as short name for "globalresourceconfig"

 

           // -----------------------------------------------------------------------------------

           // An example with input and output paths stored inside the MFX file

              System.out.println("\Executing TokenizeString.mfx...");

              if (objMFS.run("TokenizeString.mfx"))

                 System.out.println("Success: " +  objMFS.getLastExecutionMessage());

              else

                 System.out.println("Unsuccessful: " + objMFS.getLastExecutionMessage());

                 

           // ----------------------------------------------------------------------------------

           // An example creating a simple output so that we can retrieve the result explicitly

              System.out.println("\Executing SimpleTotal.mfx...");

              if (objMFS.run("SimpleTotal.mfx"))

                 System.out.println("Mapping result is: " + objMFS.getOutputParameter("total"));

              else

              {

                 // execution failed (e.g. somebody deleted file ipo.xml)

                 System.out.println(objMFS.getLastExecutionMessage());

              }

           // ----------------------------------------------------------------------------------

           // An example with parameterized input

           // the default of 'lower = 5' gets changed to the value '10'

           // mfx reads file Temperatures.xml and writes its output to Temperatures_out.xml.

           System.out.println("\Executing ClassifyTemperatures.mfx with parameter 'lower' set to '10' ...");

           objMFS.addParameter("lower", "10");

           if (objMFS.run("ClassifyTemperatures.mfx"))

              System.out.println("File Temperatures_out.xml has been written successfully.");

           else

           {

               // execution failed. maybe no write permissions in working directory? Run this program as administrator.

               System.out.println(objMFS.getLastExecutionMessage());

           }

 

           // You can stop the server explicitly by invoking the 'stop' method if you don't want to let the garbage collector decide.

              objMFS.stop();

         }

             catch (Exception e)

             {

                System.out.println("ERROR: " + e.getMessage());

             }

      }

 

}

 

© 2016-2022 Altova GmbH