2019年2月1日金曜日

[English] Check this data mapping tool! Atlasmap.io

Have you ever tried "Red Hat Fuse Online" before? It's an "integration Platform-as-a-Service (iPaaS) solution that makes it easy for business users to collaborate with integration experts and application developers".  If you've never tried it yet, please check this free trial.

https://www.redhat.com/en/technologies/jboss-middleware/fuse-online

If you know about "Red Hat Fuse Online", probably also you know that https://syndesis.io/ is the main upstream community for "Red Hat Fuse Online". How about https://www.atlasmap.io/ ?
"AtlasMap is a data mapping solution with interactive web based user interface, that simplifies configuring integrations between Java, XML, and JSON data sources." Please note that the ease of integration development is brought by AtlasMap too.

The good news is even if you are not ready for OpenShift world yet, you can still launch a standalone jar archive on your laptop to start AtlasMap web tooling. Yes, you can experience the data mapping solution within a few seconds. (Community members are still on the way to release standalone Atlasmap(issues/560), but we can try it in advance)
Of course, you can use the mapping file in your Java application. I recommend to use camel-atlasmap component because it's super easy to use.

Let me explain step by step about

  1. Download and launch Atlasmap web tooling
  2. Create data mapping
  3. Run the mapping by using Apache Camel

1: Download and launch AtlasMap web tooling

From version 1.39.0, atlasmap-standalone jar is available in maven central repository.
http://central.maven.org/maven2/io/atlasmap/atlasmap-standalone/1.39.0/atlasmap-standalone-1.39.0.jar
You can run AtlasMap standalone by `java -jar atlasmap-standalone-1.39.0.jar` which is springboot uber jar and UI is available at localhost:8585.

If you want to try latest AtlasMap source code, clone the repository and build it by yourself.
$ git clone https://github.com/atlasmap/atlasmap.git
$ cd ${ATLASMAP}
$ ./mvnw clean install -DskipTests

After booting up the web UI, you will see the console log something like this
2019-02-01 13:39:37.762  INFO 16127 --- [           main] b.c.e.u.UndertowEmbeddedServletContainer : Undertow started on port(s) 8585 (http)
2019-02-01 13:39:37.766  INFO 16127 --- [           main] io.atlasmap.standalone.Application       : Started Application in 4.816 seconds (JVM running for 5.427)
2019-02-01 13:39:37.766  INFO 16127 --- [           main] io.atlasmap.standalone.Application       : ### AtlasMap Data Mapper UI started at port: 8585 ###

2: Create data mapping

After accessing to localhost:8585, please take a look at the UI for about 5 minutes. I guess you will see what/how you can use  this tool.

On the left side panel named "Source", you can import and display the source data structure to convert.
On the right side pane named "Target", you can import and display the target data structure.

Java, XML, and JSON format is currently supported.

By moving the cursor to the arrow icon next with "Source" or "Target", you will see the pop up message "import instance or schema file".
As pop up message says, you can import xml file.(not schema file) AtlasMap will automatically analyze it for you.
Also you can import jar archive which contains multiple class files. After importing a jar archive, you can specify specific class name with package name.

By clicking each data entries from "Source" and "Target", you can do mapping.
On the right side panel named "Action", you can choose how you map data entries. (map/combine/separate)

By clicking gear icon on the right top right side corner, you can enable "Show Mapping Preview". With this feature, you can simulate the mapping using dummy data.

When you finish mapping, click export icon on the top right side to get the mapping archive.

3: Run the mapping by using Apache Camel

Using "Red Hat Developer Studio"(Eclipse) new project wizard, you can create a new sample Camel project. Please select spring boot for the run time. I select 2.21.0.fuse-720050-redhat-00001 for Red Hat Fuse version. If you love karaf container, please watch
https://github.com/atlasmap/atlasmap/issues/68.

Add camel-atlasmap dependency in the pom.xml

<dependency>
  <groupId>io.atlasmap</groupId>
  <artifactId>camel-atlasmap</artifactId>
  <version>1.40.0-SNAPSHOT</version>
</dependency>

Since 1.40.0-SNAPSHOT is not hosted on maven central repository, you need to use the one in the local maven repository.(I did mvn install with latest atlasmap git repo, so I can use 1.40.0-SNAPSHOT)

This is a sample camel route to test data mapping.
Timer consumer endpoint will fire one time. Put a sample pojo object using "sebBody", and do mapping(pojo to xml) by using camel-atlasmap. we can check the result by comparing the output log.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" http://www.springframework.org/schema/beans  http://www.springframework.org/schema/beans/spring-beans.xsd  http://camel.apache.org/schema/spring  http://camel.apache.org/schema/spring/camel-spring.xsd">
    <bean class="sample.Product" id="sampleProduct">
        <property name="id">
            <value>1</value>
        </property>
        <property name="price">
            <value>1000</value>
        </property>
    </bean>
    <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
        <route id="simple-route">
            <from id="route-timer" uri="timer:timerName?repeatCount=1"/>
            <log id="route-log1" message="hello world"/>
            <setBody id="route-setBody">
                <simple>${ref:sampleProduct}</simple>
            </setBody>
            <log id="route-log2" message="Before Mapping >>> ${body}"/>
            <to id="_to1" uri="atlas:atlasmap-mapping.adm"/>
            <log id="route-log3" message="After Mapping >>> ${body}"/>
        </route>
    </camelContext>
</beans>

This part of camel route is camel-atlasmap. atlasmap-mapping.adm file is placed under $PROJECT/src/main/resources.

<to id="_to1" uri="atlas:atlasmap-mapping.adm"/>

This is the part of output log. We can confirm that the data was converted from pojo to xml.
14:08:33.813 [main] INFO  org.mycompany.Application - Started Application in 4.41 seconds (JVM running for 4.691)
14:08:34.763 [Camel (MyCamel) thread #1 - timer://timerName] INFO  simple-route - hello world
14:08:34.768 [Camel (MyCamel) thread #1 - timer://timerName] INFO  simple-route - Before Mapping >>> sample.Product@5ed4bc
14:08:35.036 [Camel (MyCamel) thread #1 - timer://timerName] WARN  o.a.c.c.atlasmap.AtlasEndpoint - There's no source document with docId='JSONInstanceSource', returning default: docId='null', path='null'
14:08:35.037 [Camel (MyCamel) thread #1 - timer://timerName] WARN  o.a.c.c.atlasmap.AtlasEndpoint - Null or non-String source document: docId='JSONInstanceSource': docId='JSONInstanceSource', path='null'
14:08:35.037 [Camel (MyCamel) thread #1 - timer://timerName] WARN  o.a.c.c.atlasmap.AtlasEndpoint - There's no source document with docId='JSONSchemaSource', returning default: docId='null', path='null'
14:08:35.037 [Camel (MyCamel) thread #1 - timer://timerName] WARN  o.a.c.c.atlasmap.AtlasEndpoint - Null or non-String source document: docId='JSONSchemaSource': docId='JSONSchemaSource', path='null'
14:08:35.037 [Camel (MyCamel) thread #1 - timer://timerName] WARN  o.a.c.c.atlasmap.AtlasEndpoint - There's no source document with docId='XMLSchemaSource', returning default: docId='null', path='null'
14:08:35.037 [Camel (MyCamel) thread #1 - timer://timerName] WARN  o.a.c.c.atlasmap.AtlasEndpoint - Null or non-String source document: docId='XMLSchemaSource': docId='XMLSchemaSource', path='null'
14:08:35.037 [Camel (MyCamel) thread #1 - timer://timerName] WARN  o.a.c.c.atlasmap.AtlasEndpoint - There's no source document with docId='sample.Product', returning default: docId='null', path='null'
14:08:35.037 [Camel (MyCamel) thread #1 - timer://timerName] WARN  o.a.c.c.atlasmap.AtlasEndpoint - There's no source document with docId='XMLInstanceSource', returning default: docId='null', path='null'
14:08:35.037 [Camel (MyCamel) thread #1 - timer://timerName] WARN  o.a.c.c.atlasmap.AtlasEndpoint - Null or non-String source document: docId='XMLInstanceSource': docId='XMLInstanceSource', path='null'
14:08:35.037 [Camel (MyCamel) thread #1 - timer://timerName] WARN  o.a.c.c.atlasmap.AtlasEndpoint - No target document created for DataSource:[id=JSONInstanceTarget, uri=atlas:json:JSONInstanceTarget]: docId='JSONInstanceTarget', path='null'
14:08:35.037 [Camel (MyCamel) thread #1 - timer://timerName] WARN  o.a.c.c.atlasmap.AtlasEndpoint - No target document created for DataSource:[id=JSONSchemaTarget, uri=atlas:json:JSONSchemaTarget]: docId='JSONSchemaTarget', path='null'
14:08:35.039 [Camel (MyCamel) thread #1 - timer://timerName] INFO  simple-route - After Mapping >>> {JSONInstanceTarget=null, JSONSchemaTarget=null, XMLInstanceTarget=<?xml version="1.0" encoding="UTF-8" standalone="no"?>, sample=<?xml version="1.0" encoding="UTF-8" standalone="no"?><request><id>1</id><price>1000</price></request>, XMLSchemaTarget=<?xml version="1.0" encoding="UTF-8" standalone="no"?>}

For more details/instruction/latest information about AtlasMap, please visit https://www.atlasmap.io/.
I hope this post helps a bit.

Regards,
Hisao