Generate, Build, and Run Code
This topic explains how to generate code from a mapping and a project, build the generated code, and run it. There are situations in which you might need to modify your generated C#/C++/Java code to integrate it into your custom code. For details, see Integrate Generated Code.
Generate code from a mapping
To generate code from a mapping design (.mfd), follow the instructions below:
1.Select the relevant code-generation options in the Generation section of the Options dialog (applicable to C# and C++) and in the Mapping Settings. For details about the code-generation settings in the Options dialog, see Generation.
2.Click File | Generate code in and select the relevant transformation language. Alternatively, you can select File | Generate Code in Selected Language. In this case, code will be generated in the language selected in the toolbar.
3.Select a destination directory for the generated files and then click OK to confirm. MapForce generates the code and displays the result of the operation in the Messages window.
Generate code from a project (Professional and Enterprise editions)
You can generate code from a mapping project (.mfp) that consists of multiple mapping design files (.mfd). Note that all mapping design files in the project must qualify for generation, which means that all their components must be supported in the selected transformation language (see Supported features in generated code).
To generate code from a mapping project, follow the instructions below.
1.Open the relevant mapping project, for which you wish to generate code.
2.Right-click the project name in the Project window and then select Properties from the context menu. Alternatively, click the project name and select the Project | Properties menu item.
3.Review and change the project settings if required. In particular, ensure that the target language and the output directory are set correctly. Then click OK.
4.Click Generate Code for Entire Project in the Project menu.
Irrespective of the language selected in the Project Properties dialog, you can always choose to generate project code in a different language, by selecting the menu command Project | Generate Code in | <language>.
The progress and result of the code generation process is displayed in the Messages window. By default, the name of the generated application is the same as the project name. If the project name contains spaces, these are converted to underscores in the generated code. By default, code is generated in the same directory as the MapForce project, in the output sub-directory.
You can change the output directory and/or the name of the project in the Project Properties dialog. If your MapForce project contains folders, you can configure the code generation settings for each individual folder: Right-click a folder of interest and select Properties from the context menu. Otherwise, all project folders inherit the settings defined at top level. For more information about projects and project-related settings and procedures, see Projects.
Language-specific information
This subsection describes the peculiarities of generating code in different transformation languages. This subsection goes on to explain how to build the generated C++, C#, and Java code and run the application. You can also generate code in XSLT 1-3 and XQuery. For details, see Code Generation.
C++ and C# code
Generating, building, and running C++ and C# code follow the same logic. The broad procedures are outlined in the subsections below.
After you have generated C++ or C# code, the solution will include the following components:
•Solution (.sln) and project (.vcxproj for C++ and .csproj for C#) files that can be opened in Visual Studio
•Several Altova-signed libraries required by the mapping (all prefixed with Altova)
•The main mapping project (called Mapping by default), which includes the mapping application and its dependent files
Note that you can change the default name of the main mapping project in the Mapping Settings dialog box.
After you have generated the C++/C# code, the next steps would be to build the code and run the application. There are two major approaches to building the generated code: (i) in Visual Studio and (ii) at the command line (see details below). Note that, to build C# code, you must have the relevant SDK and a compatible Visual Studio version installed. For the download package for your operating system and platform, refer to the Microsoft website.
Build generated code in Visual Studio
To build the generated C++/C# code, follow the instructions below:
1.Open the generated solution (.sln) file in Visual Studio. By default, the name of the solution file is Mapping.sln, and it is located in the Mapping subdirectory relative to the directory with the generated code.
2.Select the required build configuration (e.g., Debug). Note about C++ code: only Unicode builds support the full Unicode character set in XML and other files. The non-Unicode builds work with the local codepage of your Windows installation.
3.Click Build Solution in the Build menu.
As a result of building the code, a command-line application called Mapping.exe and its related files will be created. The mapping application will be located in one of the subdirectories relative to the .sln file. The name of the subdirectory depends on the selected build configuration: e.g., Debug (C++), bin\Debug (C#).
Build generated code at command line
To build the generated code at the command line, switch to the directory with the generated code and run the following command:
devenv Mapping.sln /Build "Debug|AnyCPU" /Project Mapping
This command calls Visual Studio and specifies the name of the solution file to build (Mapping.sln in our case), the desired configuration (Debug and any CPU in our case), and the name of the project the solution file belongs to (Mapping). As a result of building the code, a command-line application called Mapping.exe and its related files will be created. The mapping application will be located in one of the subdirectories relative to the .sln file. The name of the subdirectory depends on the selected build configuration: e.g., Debug (C++), bin\Debug (C#).
Notes about building C# code
Besides calling Visual Studio, you can also call .NET to build the generated C# code. Follow the instructions below:
1.Make sure to select the correct platform to target in the Generation section of the Options dialog (Tools menu). For details, see Generation.
2.If you target .NET/.NET Core, configure the PATH and DOTNET_ROOT environment variables so that they point to the location where .NET/.NET Core is installed. This will prevent possible problems with CLI commands.
3.Open a command prompt and switch to the directory with the generated code.
4.Run the following command:
dotnet build Mapping\Mapping.sln --configuration Release
This command calls .NET to build the solution file called Mapping.sln with the Release configuration and creates an executable called Mapping.exe and its related files at the destination folder. The name of the destination folder depends on the selected configuration and the .NET version used. In our example, the executable will be saved in the bin\Release\net8.0 folder.
Run application
After you have built the code in Visual Studio directly or at the command line, you can proceed to run the application. To run the application, double-click Mapping.exe or call the executable from the command line. After you have run the executable, the result of the mapping transformation will be output to the destination folder (by default, this is the folder where the executable is stored).
If you build the generated code on Linux, the generated executable will be called Mapping, without any extension. To run the executable, you may need to use the following command:
./Mapping
Java code
After you have generated Java code, the Java project will include the following components:
•Several Altova-signed Java packages required by the mapping (all prefixed with com.altova)
•The com.mapforce package including the mapping application and its dependent files, among which the two most important files that specify the entry points of the application are the following:
oThe Java mapping application as a dialog application (MappingApplication.java)
oThe Java mapping application as a console application (MappingConsole.java)
•The build.xml file which you can execute with Apache Ant to compile the project and generate JAR files
The default names of the mapping application and its dependent files in the com.mapforce package are prefixed with Mapping. You can change this and other settings in the Mapping Settings dialog box.
After you have generated Java code, the next steps would be to build and run the code. There are two major approaches to building the generated code and running the application: (i) in Eclipse and (ii) at the command line, using Apache Ant. The broad procedures are described in the subsections below.
Build generated code and run application in Eclipse
This approach makes use of the Eclipse workflow. Note the following prerequisites:
•Java Development Kit (JDK), Eclipse, and Apache Ant must be installed on your system. Eclipse typically includes a bundled version of Ant, but you can also install Ant separately.
•To run Eclipse with OpenJDK, you need to set the PATH environment variable so that it includes the path to the JDK bin directory (e.g., C:\Java\jdk-11.0.1\bin).
•The JAVA_HOME environment variable must point to the location of JDK.
•The ANT_HOME environment variable must point to the location of Apache Ant.
After you have generated Java code, the next step is to import the generated Java code into Eclipse. Follow the steps below:
1.In the File menu, click Import and select General | Existing Projects into Workspace.
2.Click Next.
3.Provide the path to the generated code and click Finish. The Java project created by MapForce is now available in the Package Explorer view. If you cannot see the Package Explorer view, use the menu command Window | Show View | Package Explorer.
Note that, by default, code is built automatically each time a change is detected. You can also disable this functionality and build code when necessary (see the Eclipse documentation for details).
After you have imported and built your code, the next step is to run the application. This topic discusses some of the possible approaches to running an application.
Approach 1: Run project as an application
This method allows you to run your Java project as a GUI application. Take the steps below:
1.In the Package Explorer view of Eclipse, right-click the MappingApplication.java file in the com.mapforce package.
2.Select Run As | Java application from the context menu.
3.In the MapForce application window that pops up, click Start to execute the mapping.
Approach 2: Run project as a console application
This method enables you run your Java project as a console (command-line) application. Take the steps below:
1.In the Package Explorer view of Eclipse, right-click the MappingConsole.java file in the com.mapforce package.
2.Select Run As | Java application from the context menu.
As a result of running the application, irrespective of the approach selected, the Java application will execute the mapping transformation and generate output file(s) at the destination folder.
Build generated code and run application at command line
To be able to build and run your generated code at the command line, you must have the following components installed and environment variables set:
•Java Development Kit (JDK) and Apache Ant must be installed on your system.
•The location of the Ant bin directory (e.g., C:\apache-ant-1.10.5\bin) should be added to the PATH environment variable. This will enable you to conveniently run Ant without having to type the full path to the executable at the command line.
•The JAVA_HOME environment variable must point to the location of JDK.
•The ANT_HOME environment variable must point to the location of Apache Ant.
To build the generated code with Apache Ant, follow the instructions below:
1.Open a command prompt and switch to the directory where the generated code, including the build file (build.xml), is stored.
2.Run the following command:
ant jar
This command will build the generated code and create a JAR file (called Mapping.jar by default). The purpose of the JAR file is to package Java .class files and their related metadata and resources. In our case, the JAR archive is intended to be used as an executable Java program; therefore, the archive's manifest file includes the entry point of the application (by default, com.mapforce.MappingConsole).
To run the Java application, run the following command in the directory where the JAR archive is located:
java com.mapforce.MappingConsole Mapping.jar
This command starts the Java Virtual Machine, launches the main class called com.mapforce.MappingConsole, which refers to the entry point of the Java application, and executes the program contained in the JAR file called Mapping.jar. As a result, the Java application will execute the mapping transformation and generate output file(s) at the destination folder. If you want to launch the application as a GUI application, pass the following value for the main class argument: com.mapforce.MappingApplication. This will open a pop-up window, in which you will be able to start the mapping transformation.
Preventing possible out-of-memory issues
Complex mappings with large schemas can produce a large amount of code, which might cause a java.lang.OutofMemory exception during compilation in Ant. To prevent possible out-of-memory issues, take the steps below:
1.Add the ANT_OPTS environment variable, which sets specific Ant options such as the memory to be allocated to the compiler, and set its value as follows: -server -Xmx512m -Xms512m.
2.To make sure that the compiler and the generated code run in the same process as Ant, change the fork attribute in build.xml to false.
You may need to customize the values depending on the amount of memory in your machine and the size of the project you are working with. For more details, see your Java VM documentation.
When you run the ant jar command, you may get an error message similar to "[...] archive contains more than 65535 entities". To prevent this, it is recommended to use Ant 1.9 or later and to add zip64mode="as-needed" to the <jar> element in build.xml.
Preventing possible issues with JDBC connections
If you have generated Java code from a mapping that connects to a database through JDBC, you may need to add the JDBC driver as a classpath entry to the current configuration. Otherwise, running the application could result in an error. For details, see Databases.