| {"name":"Template-for-PPMP-transformation","content":"<h1>Quick start</h1>\n<p>In <a href=\"https://www.eclipse.org/unide/blog/2018/2/11/Transform-PPMP-with-camel/\">a previous blog post</a>, I have already introduced Apache Camel as a tool to transform to PPMP. In this post, I want to dive a little deeper to get you started with your own transformation.<br>\nYou can find corresponding source code with some transformation examples <a href=\"https://github.com/eclipselabs/eclipseiot-testbed-productionperformancemanagement/tree/master/camel-integrator\">in the repository of the Eclipse PPM Testbed</a>. After download or checkout of the project, you can easily package everything necessary for an installation via <a href=\"https://maven.apache.org/\">Apache Maven</a> and java 8+:</p>\n<pre class=\"language-bash\"><code class=\"language-bash\"><span class=\"token function\">git</span> clone https://github.com/eclipselabs/eclipseiot-testbed-productionperformancemanagement.git\n<span class=\"token function\">cd</span> eclipseiot-testbed-productionperformancemanagement\n<span class=\"token function\">cd</span> camel-integrator\nmvn package\n</code></pre>\n<p>After successful build, you should get a zip file at <code>target/camel-integrator-*-assembly.zip</code> with the following content</p>\n<ul>\n<li><code>bin</code><br>\nThe IntegratorStarter* files for Windows and Linux can be used to start the integrator manually. WinServiceInstaller.bat und WinServiceUninstaller.bat can be executed with Admin permissions in Windows to register/unregister this java application as Windows Service called "Integrator Service".</li>\n<li><code>conf</code><br>\nThis is where the main configuration file <code>application-context.xml</code>, further included spring xml configurations, as well as the configuration for logging <code>log4j.properties</code> and a key-value-file for quick configuration <code>application.properties</code> can be found. After modification of any of them, the integrator should be restarted.</li>\n<li><code>lib</code><br>\nContains all java dependencies and their dependencies as individual jar files</li>\n<li><code>log</code><br>\nAfter the first start, you will find an additional directory that contains the logs of every execution, as defined in the <code>conf/log4j.properties</code> file.</li>\n</ul>\n<p>So this <code>camel-integrator-*-assembly.zip</code> is all you need, ready to being shipped and installed in your target system.</p>\n<h1>How can I modify this?</h1>\n<p>In the <code>conf</code> folder of the output or <code>src/main/resources</code> src folder, you'll find multiple examples on how to use Apache Camel with Production Performance Management Protocol. Most of the examples are based on <a href=\"https://github.com/apache/camel/blob/master/components/camel-spring/src/main/docs/spring.adoc\">spring xml</a>.<br>\nThe most important terms to understand them are:</p>\n<table>\n<thead>\n<tr>\n<th>xml tag</th>\n<th>meaning</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>bean</td>\n<td>additional functionality, coded as java class / function</td>\n</tr>\n<tr>\n<td>camelContext</td>\n<td>the main, camel specific configurations</td>\n</tr>\n<tr>\n<td>route</td>\n<td>describes the data flow as process</td>\n</tr>\n<tr>\n<td>from / to</td>\n<td>entry / exit points for the data flow. This is also, were external systems are accessed via <a href=\"https://github.com/apache/camel/tree/camel-2.21.0/components\">components</a></td>\n</tr>\n<tr>\n<td>onException</td>\n<td>error handling for the data flow</td>\n</tr>\n<tr>\n<td>pipeline, multicast, ...</td>\n<td>routing of data via <a href=\"http://camel.apache.org/enterprise-integration-patterns.html\">Enterprise Integration pattern</a></td>\n</tr>\n</tbody>\n</table>\n<p>Among others, you'll find:</p>\n<div class=\"card figure is-pulled-right\">\n\t<div class=\"card-image\">\n\t\t<figure class=\"image\">\n\t\t\t<img alt=\"html log file\" title=\"html log file\" src=\"/unide/images/blog/Transform-PPMP-with-camel-2-logfile.png\"></img>\n\t\t</figure>\n\t</div>\n\t<div class=\"card-content\">\n\t\thtml logfile before transformation to PPMP\n\t</div>\n</div>\n<ul>\n<li><code>application-context.xml</code><br>\nMain entry file to start camel routes. It contains a general PPMP validation REST endpoint that reuses the route from <code>ppmp-validate-context.xml</code></li>\n<li><code>mqtt-context.xml</code><br>\nA simple example of converting transport protocol (mqtt to REST), without looking at the payload</li>\n<li><code>ppmp-splitAndRewrite-context.xml</code><br>\nShows how to receive (PPMP-) payload via different REST paths (/rest or /ppm), and each forwarding to two seperate endpoints (/rest and /ppm)\n<ul>\n<li><code>ppmpRewrite.xml</code> and <code>ppmRewrite.xml</code><br>\nmapping examples to rewrite the urls</li>\n</ul>\n</li>\n<li><code>ppmp-validate-context.xml</code><br>\nA simple validation route for PPMP messages that can be reused in many other routes.</li>\n<li><code>psi6000-transform-context.xml</code><br>\nA more advanced example of converting a psi6000 JSON format, converting it to plain old java object (POJO), transforming that to PPMP POJOs (using <a href=\"https://github.com/eclipse/unide.java\">unide.java</a>) and forwarding these to actual REST endpoints</li>\n<li><code>kistler.xml</code><br>\nThis example takes html files with a structure similar to the test file in <a href=\"https://github.com/eclipselabs/eclipseiot-testbed-productionperformancemanagement/blob/master/camel-integrator/src/test/data/00000855.html\"><code>src/test/data/00000855.html</code></a>, cleans the html structure, retrieves the relevant parts via <a href=\"https://en.wikipedia.org/wiki/XPath\">XPath</a> and creates a PPMP process message out of that</li>\n<li><code>application.properties</code><br>\nContains key/value pairs that can be used in the camel context configurations.</li>\n<li><code>log4j.properties</code><br>\nThe configuration for logging. For testing purposes, the log4j.properties in /src/test/resources is used.</li>\n</ul>\n<p>In order to get familiar with these transformations, I suggest you:</p>\n<ul>\n<li>open the <code>application-context.xml</code> in your favorite editor</li>\n<li>remove the <code><import .../></code> statements</li>\n<li>add your own <code><route>...</route></code>, maybe as simple as<pre class=\"language-xml\"><code class=\"language-xml\"> <span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"><</span>route</span><span class=\"token punctuation\">></span></span>\n \t<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"><</span>from</span> <span class=\"token attr-name\">uri</span><span class=\"token attr-value\"><span class=\"token punctuation\">=</span><span class=\"token punctuation\">\"</span>jetty:http://0.0.0.0:9090/<span class=\"token punctuation\">\"</span></span> <span class=\"token punctuation\">/></span></span>\n \t<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"><</span>setBody</span><span class=\"token punctuation\">></span></span>\n \t\t<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"><</span>simple</span><span class=\"token punctuation\">></span></span>hello world!<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"></</span>simple</span><span class=\"token punctuation\">></span></span>\n \t<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"></</span>setBody</span><span class=\"token punctuation\">></span></span>\n <span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"></</span>route</span><span class=\"token punctuation\">></span></span>\n</code></pre>\n</li>\n<li>start a run directly (with bundling to a zip file) with:<pre class=\"language-bash\"><code class=\"language-bash\"> mvn exec:java\n</code></pre>\n</li>\n<li>and review the result. With the example above, just open the url <a href=\"http://localhost:9090\">http://localhost:9090</a> and see the <code>hello world!</code> in your browser</li>\n</ul>\n<p>If you prefer a visual model of these camel xml definitions, you could also make use of <a href=\"https://tools.jboss.org/features/fusetools.html\">JBoss Fuse Tooling</a> which is available for <a href=\"https://projects.eclipse.org/releases/oxygen\">Eclipse Workbench 4.3+</a> through <a href=\"https://marketplace.eclipse.org/content/jboss-tools\">the Marketplace</a>. Be aware that this might cause additional overhead.</p>\n<div class=\"card figure\">\n\t<div class=\"card-image\">\n\t\t<figure class=\"image\">\n\t\t\t<img alt=\"JBoss Tools\" title=\"JBoss Tools for Eclipse Workbench\" src=\"/unide/images/blog/Transform-PPMP-with-camel-2-eclipse.png\"></img>\n\t\t</figure>\n\t</div>\n\t<div class=\"card-content\">\n\t\tJBoss Tools for Eclipse Workbench\n\t</div>\n</div>\n<p>If you want to make use of any other of the (as of camel 2.21.0) <a href=\"https://github.com/apache/camel/tree/camel-2.21.0/components\">281+ components</a>, you should add the respective maven dependency to the <code>pom.xml</code>. For example:</p>\n<pre class=\"language-xml\"><code class=\"language-xml\"><span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"><</span>project</span> <span class=\"token attr-name\">xmlns</span><span class=\"token attr-value\"><span class=\"token punctuation\">=</span><span class=\"token punctuation\">\"</span>http://maven.apache.org/POM/4.0.0<span class=\"token punctuation\">\"</span></span> <span class=\"token attr-name\"><span class=\"token namespace\">xmlns:</span>xsi</span><span class=\"token attr-value\"><span class=\"token punctuation\">=</span><span class=\"token punctuation\">\"</span>http://www.w3.org/2001/XMLSchema-instance<span class=\"token punctuation\">\"</span></span>\n\t<span class=\"token attr-name\"><span class=\"token namespace\">xsi:</span>schemaLocation</span><span class=\"token attr-value\"><span class=\"token punctuation\">=</span><span class=\"token punctuation\">\"</span>http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd<span class=\"token punctuation\">\"</span></span><span class=\"token punctuation\">></span></span>\n\t...\n\t<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"><</span>dependencies</span><span class=\"token punctuation\">></span></span>\n\t\t<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"><</span>dependency</span><span class=\"token punctuation\">></span></span>\n\t\t\t<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"><</span>groupId</span><span class=\"token punctuation\">></span></span>org.apache.camel<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"></</span>groupId</span><span class=\"token punctuation\">></span></span>\n\t\t\t<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"><</span>artifactId</span><span class=\"token punctuation\">></span></span>camel-amqp<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"></</span>artifactId</span><span class=\"token punctuation\">></span></span>\n\t\t\t<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"><</span>version</span><span class=\"token punctuation\">></span></span>${camel.version}<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"></</span>version</span><span class=\"token punctuation\">></span></span>\n\t\t<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"></</span>dependency</span><span class=\"token punctuation\">></span></span>\n\t...\n\t<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"></</span>dependencies</span><span class=\"token punctuation\">></span></span>\n\t...\n<span class=\"token tag\"><span class=\"token tag\"><span class=\"token punctuation\"></</span>project</span><span class=\"token punctuation\">></span></span>\n</code></pre>\n<h1>Testing</h1>\n<p>Testing is an important part of the development cycle, especially for the core components that have to work reliably in a production environment.<br>\nThe project includes example tests in the <code>src/test</code> folder:</p>\n<ul>\n<li><code>java</code><br>\ncontains the actual java unit tests that make use of <a href=\"https://github.com/apache/camel/blob/61a58836da57bab38ce719cbd1effd36253687a4/docs/user-manual/en/spring-testing.adoc\"><code>CamelSpringTestSupport</code></a> to wire xml CamelContext configuration, test data and expected results together</li>\n<li><code>resources</code><br>\ncontains the spring xml configuration that is used by the java test classes and resamble the actual configurations from <code>src/main/resources</code></li>\n<li><code>data</code><br>\ncontains testdata for the data flows and the transformation</li>\n</ul>\n<p>Tests can easily be run from within an IDE (eclipse, visual code studio etc.) or via commandline</p>\n<pre class=\"language-bash\"><code class=\"language-bash\">mvn <span class=\"token function\">test</span>\n</code></pre>\n<p>You will see the output of the test runs. If it looks like this, it works as expected:</p>\n<pre class=\"language-bash\"><code class=\"language-bash\">Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 2.846 sec\n\nResults <span class=\"token keyword\">:</span>\n\nTests run: 3, Failures: 0, Errors: 0, Skipped: 0\n\n<span class=\"token punctuation\">[</span>INFO<span class=\"token punctuation\">]</span> ------------------------------------------------------------------------\n<span class=\"token punctuation\">[</span>INFO<span class=\"token punctuation\">]</span> BUILD SUCCESS\n<span class=\"token punctuation\">[</span>INFO<span class=\"token punctuation\">]</span> ------------------------------------------------------------------------\n<span class=\"token punctuation\">[</span>INFO<span class=\"token punctuation\">]</span> Total time: 32.267 s\n<span class=\"token punctuation\">[</span>INFO<span class=\"token punctuation\">]</span> Finished at: 2018-04-09T15:25:25+02:00\n<span class=\"token punctuation\">[</span>INFO<span class=\"token punctuation\">]</span> Final Memory: 25M/85M\n<span class=\"token punctuation\">[</span>INFO<span class=\"token punctuation\">]</span> ------------------------------------------------------------------------\n</code></pre>\n<h1>Summary</h1>\n<p>The provided camel project template facilitates the creation of simple connectors. You can download it, modify or extend it, package the integrator to a zip file and deploy it on a target server. The included scripts help registering the integrator as an operating system service to run 24/7.</p>\n","url":"/blog/2018/9/4/Template-for-PPMP-transformation","title":"PPMP Use Cases: Template for PPMP transformation","date":"2018-09-04T00:00:00.000Z","tags":["use cases"],"prev":{"url":"/blog/2018/3/26/Release-0.2.0","title":"Unide 0.2.0 released"},"next":{"url":"/blog/2019/3/1/Version-3","title":"PPMP Version 3 release candidate"}} |