Import Custom Java and .NET Libraries
This section explains how to import compiled Java class files and .NET DLL assemblies (including .NET 4.0 assemblies) into MapForce. If the imported libraries contain functions that use basic data types as parameters and return simple types, such functions appear in the Libraries window and can be used in mappings as any other function available in MapForce. The mapping output of imported Java and .NET functions can be previewed in the Output pane, and the functions are available in the generated code. To find out more about importing custom libraries, see the examples provided in Import Custom Java Class and Import Custom .NET DLL Assembly.
Important:
•To import custom Java or .NET functions, you need compiled Java classes (.class) or .NET.dll assembly files. The import of Java .jar files or .dll files that are not a .NET assembly is not supported.
•.NET assembly files are supported when the mapping language is set to C#. The .NET assemblies may be written in .NET languages other than C# (e.g., C++.NET or VB.NET) if they use only the basic data types from the System Assembly as parameters and return types. For details, see .NET Function Support.
•If you want to use custom .NET functions in the built-in output preview (in the Output pane), these functions need to be compiled for .NET Framework 4.x or .NET Standard 2.0.
•Compiled Java class (.class) files are supported when the mapping language is set to Java. Java Runtime Environment 7 or later must be installed on your computer. Only specific types and members are supported (see Java function support).
•You cannot set the mapping language to C++ if the mapping uses imported Java .class or .NET DLL assemblies.
•You cannot set the mapping language to XSLT if the mapping uses imported Java .class or .NET DLL assemblies (a custom XSLT function that acts as an adapter would have to be written).
•The import of functions from native C++ DLLs is limited and requires a special approach. For more information, see Reference Java, C# and C++ Libraries Manually.
•All functions called from a MapForce mapping should return the same value each time the function is called with the same input parameters. The exact order and the number of times a function is called by MapForce is undefined.
•In the case of Java, the imported class files and their packages do not need to be added to the CLASSPATH variable since the Built-in execution engine and generated Java code will automatically add imported packages to the Java engine’s classpath or to Ant, respectively. However, any dependencies of the imported class files and packages will not be handled automatically. Therefore, if imported Java class files or packages depend on other class files, make sure to add the parent directories of all dependent packages to the CLASSPATH environment variable.
Java function support
Top-level classes, static member classes and non-static member classes are supported:
•new <classname>(<arg1>, <arg2>, ...)
•<object>.new <member-class>(<arg1>, <arg2>, ...)
Member functions and static functions are supported:
•<function>(<arg1>, <arg2>, ...)
•<object>.<method>(<arg1>, ...)
Supported connections between XML Schema and Java types:
Schema type | Java type |
|---|---|
xs:string | String |
xs:byte | byte |
xs:short | short |
xs:int | int |
xs:long | long |
xs:boolean | boolean |
xs:float | float |
xs:double | double |
xs:decimal | java.math.BigDecimal |
xs:integer | java.math.BigInteger |
Connections in both directions are possible. Other Java types (including array types) are not supported. Methods using such parameters or return values, will be ignored. Object types are supported by calling their constructor or as a return value of a method. They can be mapped to other Java methods. Manipulating the object using MapForce means is not possible.
.NET function support
Top-level classes and member classes are supported:
•new <classname>(<arg1>, <arg2>, ...)
Member functions and static functions are supported:
•<function>(<arg1>, <arg2>, ...)
•<object>.<method>(<arg1>, ...)
Supported connections between XML Schema and .NET/C# types:
Schema type | .NET type | C# type |
|---|---|---|
xs:string | System.String | string |
xs:byte | System.SByte | sbyte |
xs:short | System.Int16 | short |
xs:int | System.Int32 | int |
xs:long | System.Int64 | long |
xs:unsignedByte | System.Byte | byte |
xs:unsignedShort | System.UInt16 | ushort |
xs:unsignedInt | System.UInt32 | uint |
xs:unsignedLong | System.UInt64 | ulong |
xs:boolean | System.Boolean | bool |
xs:float | System.Single | float |
xs:double | System.Double | double |
xs:decimal | System.Decimal | decimal |
Connections in both directions are possible. Other .NET/C# types (including array types) are not supported. Methods using such parameters or return values will be ignored. Object types are supported by calling their constructor or as a return value of a method. They can be mapped to other .NET methods. Manipulating the object using MapForce means is not possible.
Data type issues and workarounds
When a function in your custom library expects integer types, connecting constants of type Number to the function's arguments may cause a type mismatch error similar to this one: No match for MyCustomClassLibrary, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null.MyCustomClassLibrary.Converter.AddValues(MyCustomClassLibrary.Converter, xs:decimal, xs:decimal). Check argument types. This issue is specific to constants of type Number only. A sample mapping that could generate this error is shown below. In this mapping, two constants of type Number are connected to the function's arguments of type Integer.
The possible workarounds are described below:
1.Change the constant type from Number to All other. You can do this after double-clicking the title bar of the constant component.
2.Instead of a constant, use a source component (for example, an XML file) that provides values of the data type expected by the function.
3.In your external code, create a wrapper function that accepts a decimal value and returns an integer value. The wrapper solution may be imported as a separate library. Therefore, you do not need to change the original source code of the target function to use this approach.