Appendix A - IPF development

Environment

Java

IPF currently requires Java SE 6 for both compile time and runtime. Before continuing make sure you have the Java SE 6 SDK installed.

Maven

IPF uses Maven 2 as its build tool. If you haven't installed Maven 2 yet go to the Maven download page and download version 2.0.9 or higher and follow the installation instructions. It is most likely that you will have to make some additional configuration in the Maven settings.xml file.

Location of settings.xml You can find the settings.xml file in the .m2 folder in your home directory (~/.m2/settings.xml on Unix-based systems and %homepath%\.m2\settings.xml on Windows). If the file is not there then copy it from $M2_HOME/conf/settings.xml where $M2_HOME is the root folder of your Maven installation.

If you're using a proxy to access the internet you'll need to add the proxy settings to Maven's settings.xml file. Here is the template, note that some fields are optional (id, nonProxyHosts) and the username/password required only if you have to authenticate against your proxy.

...
	<proxies>
		<proxy>
			<id>optional</id>
			<active>true</active>
			<protocol>http</protocol>
			<username>proxyuser</username>
			<password>proxypass</password>
			<host>proxy.host.net</host>
			<port>80</port>
			<nonProxyHosts>local.net,some.host.com</nonProxyHosts>
		</proxy>
	</proxies>
...

Also add the following openehealth profile to the <profiles> section in your settings.xml file.

...
		<profile>
			<id>openehealth</id>
			<activation>
				<activeByDefault>true</activeByDefault>
			</activation>
			<repositories>
				<repository>
					<id>openehealth.releases</id>
					<name>Open eHealth Maven Repository</name>
					<url>http://repo.openehealth.org/maven2/releases</url>
					<releases>
						<enabled>true</enabled>
					</releases>
					<snapshots>
						<enabled>false</enabled>
					</snapshots>
				</repository>
				<repository>
					<id>openehealth.snapshots</id>
					<name>Open eHealth Maven Repository</name>
					<url>http://repo.openehealth.org/maven2/snapshots</url>
					<releases>
						<enabled>false</enabled>
					</releases>
					<snapshots>
						<enabled>true</enabled>
					</snapshots>
				</repository>
				<repository>
					<id>java.net</id>
					<name>java.net Maven Repository</name>
					<url>http://download.java.net/maven/2/</url>
				</repository>
				<repository>
					<id>codehaus</id>
					<name>Codehaus Maven Repository</name>
					<url>http://repository.codehaus.org</url>
				</repository> 
				<repository>
					<id>jboss</id>
					<name>JBoss Maven Repository</name>
					<url>http://repository.jboss.com/maven2</url>
				</repository>
                                <repository>
                                    <id>hapi-sf</id>
                                    <name>HAPI Sourceforge Repository</name>
                                    <url>http://hl7api.sourceforge.net/m2</url>
                                </repository>        
			</repositories>
		</profile>
...

You can also use this predefined settings.xml file. The openehealth profile is needed if you want to use IPF archetypes without building IPF on your local machine. That's usually the case for the IPF tutorials.

Eclipse

To work with IPF in Eclipse, we recommend a clean installation of the latest Eclipse 3.5 classic package with the following additional plugins:

In the Eclipse IDE, the plug-ins listed above can be installed from Help->Software Updates...->Available Software.The updates sites of the plug-ins are as follows:

Maven plugin version Note, that the version of Maven Integration for Eclipse is 0.9.3. If a version higher is used, you will not be able to set the custom output folders in eclipse. This 0.9.3 version of maven integration plugin will be available from the update site only if checkbox "Show only the latest versions of available software" in the Eclipse update dialog is unchecked!!

Maven plugin warnings If you see the warning "Eclipse is running in a JRE, but a JDK is required...", edit your eclipse.ini file, adding a -vm option at the beginning with the full path to the JDK's javaw.exe (on Windows). Make sure that the path to the IDE-defined JRE is a path to the corresponding JDK. For example: -vm C:/Program Files/Java/jdk1.6.0_14/bin/javaw

If you develop for the Open eHealth IPF projects, it is recommended to use these two files to customize the Java code formatter for Open eHealth IPF projects:

• profile.xml: Import this file from the Window->Preferences->Java->Code Style->Formatter dialog.
• template.xml: Import this file from the Window->Preferences->Java->Code Style->Code Templates dialog.

Sources

Checkout via command line

IPF uses Subversion for source code management. If you haven't installed a Subversion command-line tool yet go to the Subversion site, download one and install it. To checkout the the latest IPF 1.x snapshot enter

svn co --username anonymous http://gforge.openehealth.org/svn/ipf/trunk ipf

on the command line. This will create a local ipf directory containing the IPF sources. If you are prompted for a password, simply use an empty string.

Issues with long path names under Windows You might encounter issues with long path names when using Subversion client on a Windows command line. If so you might want to use the TortoiseSVN (see also next section).

Checkout via TortoiseSVN

If you don't want to work with Subversion on the command line you can alternatively use TortoiseSVN, for example. After installation create an empty ipf folder, right-click on it and select SVN Checkout.... This will open the following dialog

Enter http://gforge.openehealth.org/svn/ipf/trunk into the URL of repository field and press OK. You'll be prompted for username and password. Enter anonymous for the username, leave the password field empty, select the Save authentication checkbox and press OK.

This will checkout the IPF trunk into the folder defined in the Checkout directory field. If checkout doesn't work you're probably behind a proxy. To configure TortoiseSVN for using a proxy right-click somewhere in the Windows Explorer and select TortoiseSVN->Settings. The TortoiseSVN Settings dialog opens. Select Network and adjust the proxy settings accordingly.

Checkout via Subclipse

You can also use the Subclipse plugin to handle the IPF sources. Just open the SVN Repository Exploring perspective inside of the Eclipse and in the SVN Repositories view simply add the IPF's Repository location and check it out directly into your Workspace.

Note: you may need to configure the proxy settings inside the Eclipse to be able to make a checkout with the Subclipse. Also for anonymous login you need to provide the username=anonymous and the password field should be empty.

Structure

After checking out the sources you should see a project structure as depicted in the next two figures. The folders correspond to IPF components and namespaces which are described in more detail in the component architecture section of the IPF architecture page.

Figure: IPF project structure.

Binaries

Build

Before starting the build the MAVEN_OPTS must be adjusted. Under Windows enter

set MAVEN_OPTS=-Xmx512m -XX:MaxPermSize=128m

To build IPF binaries from the sources change the working directory to the ipf folder created in the previous step and enter

mvn install

on the command line. The binaries will be stored in the local Maven cache (.m2/repository in your home directory).

Use

IPF binaries are also available in the Open eHealth Maven Repository. To use the IPF binaries and the binaries IPF depends on, you have to define the following repositories in your pom.xml file.

...
<repositories>
    <repository>
        <id>openehealth.releases</id>
        <name>Open eHealth Maven Repository</name>
        <url>http://repo.openehealth.org/maven2/releases</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>openehealth.snapshots</id>
        <name>Open eHealth Maven Repository</name>
        <url>http://repo.openehealth.org/maven2/snapshots</url>
        <releases>
            <enabled>false</enabled>
        </releases>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
    <repository>
        <id>java.net</id>
        <name>java.net Maven Repository</name>
        <url>http://download.java.net/maven/2/</url>
    </repository>
    <repository>
        <id>jboss</id>
        <name>JBoss Maven Repository</name>
        <url>http://repository.jboss.com/maven2</url>
    </repository>
</repositories>
...

Defining repositories is not needed if you have created an openehealth Maven profile in settings.xml. Depending on your project needs you might want to define different sets of dependencies. For example, the following dependencies will transitively include all IPF dependencies.

<dependency>
    <groupId>org.openehealth.ipf.platform-camel</groupId>
    <artifactId>platform-camel-flow</artifactId>
    <version>${ipf-version}</version>
</dependency>
<dependency>
    <groupId>org.openehealth.ipf.platform-camel</groupId>
    <artifactId>platform-camel-hl7</artifactId>
    <version>${ipf-version}</version>
</dependency>

where ${ipf-version} must be replaced with the IPF version you want to use. If you don't need flow management or HL7 message processing then you might want to include the IPF Core dependencies only.

<dependency>
    <groupId>org.openehealth.ipf.platform-camel</groupId>
    <artifactId>platform-camel-core</artifactId>
    <version>${ipf-version}</version>
</dependency>

For HL7 message processing independent of Apache Camel you only need to include

<dependency>
    <groupId>org.openehealth.ipf.modules</groupId>
    <artifactId>modules-hl7dsl</artifactId>
    <version>${ipf-version}</version>
</dependency>
<dependency>
    <groupId>org.openehealth.ipf.modules</groupId>
    <artifactId>modules-hl7</artifactId>
    <version>${ipf-version}</version>
</dependency>

If you only want to use IPF's HAPI DSL without using pre-defined HL7 message processing POJOs you can omit the modules-hl7 dependency.

<dependency>
    <groupId>org.openehealth.ipf.modules</groupId>
    <artifactId>modules-hl7dsl</artifactId>
    <version>${ipf-version}</version>
</dependency>

If you're using IPF archetypes all required entries in the pom.xml file will be created for you.

Projects

Eclipse import

To setup all IPF sources within Eclipse navigate to File->Import->Existing Projects into Workspace in the Eclipse menu and select the created ipf folder as root directory. You'll see a list of all IPF projects (components).

Should you wish to import only specific projects un-check the projects that you don't want to import. An alternative is to select only the desired sub-folder of ipf. For example, to include all platform-camel projects, select the ipf/platform-camel folder. To import the projects press Finish. The list of imported projects will appear in the package explorer.

Archetypes

Overview

IPF provides Maven archetypes for most commonly used IPF project types. To generate a project from an IPF Maven archetype use the following command.

mvn org.apache.maven.plugins:maven-archetype-plugin:2.0-alpha-4:generate 
-DarchetypeGroupId=org.openehealth.ipf.archetypes 
-DarchetypeArtifactId=<ipf-archetype-name> 
-DarchetypeVersion=<ipf-archetype-version>

where <ipf-archetype-name> must be replaced with the name of the archetype you want to use and ipf-archetype-version with the version of that archetype i.e. the IPF version you want to use. Currently IPF provides the following archetypes

The above command will prompt the user to enter the project's

• groupId
• artifactId
• version
• package

Alternatively, you can define these values on the command line via

mvn org.apache.maven.plugins:maven-archetype-plugin:2.0-alpha-4:generate 
-DarchetypeGroupId=org.openehealth.ipf.archetypes 
-DarchetypeArtifactId=<ipf-archetype-name> 
-DarchetypeVersion=<ipf-archetype-version> 
-DgroupId=<project-group-id> 
-DartifactId=<project-artifact-id> 
-Dversion=<project-version> 
-DinteractiveMode=false

where project-group-id must be replaced with the project's group id, project-artifact-id with the projects artifact id and version with the project's version.

Example

This is an example how to use the ipf-archetype-basic archetype:

Create project

The create a project from the ipf-archetype-basic archetype enter

mvn org.apache.maven.plugins:maven-archetype-plugin:2.0-alpha-4:generate 
-DarchetypeGroupId=org.openehealth.ipf.archetypes 
-DarchetypeArtifactId=ipf-archetype-basic 
-DarchetypeVersion=2.0.0 
-DgroupId=com.mycompany 
-DartifactId=example 
-Dversion=1.0-SNAPSHOT 
-DinteractiveMode=false

on the command line. This creates an IPF project in a folder named example.

To compile the sources and install the generated artifacts into your local Maven cache change to the example and enter the following command.

mvn install

Create assembly

To assemble a distribution package from the project that contains all dependencies jars enter

mvn assembly:assembly

on the comamnd line. The created package (example-1.0-SNAPSHOT-bin.zip) is located in the project's target folder. When you copy and extract the folder to a new location a folder named example-1.0-SNAPSHOT is created. It contains Windows and Linux startup-scripts for starting the example integration server.

Eclipse import

The project under the example folder also contains Eclipse .project and .classpath files and a .settings folder with Eclipse settings so that the project can be readily imported into Eclipse. It is recommended that you use an Eclipse IDE as described in the Eclipse section on this page. The following screenshot shows the example project imported into Eclipse.

Clean project after import Eclipse might report compile errors for the imported project. In this case it is sufficient to clean the com.mycompany.example project. Select the project and then select Project->Clean ... from the main menu. In the dialog select Clean projects selected below (make sure that the com.mycompany.example project is actually selected) and press the OK button.

• To execute the unit tests right-click on SampleRouteTest.java and select Run As->JUnit Test from the context menu.
• To startup the integration server right-click on SampleServer.java and select Run As->Java Application from the context menu.

IntelliJ IDEA

Starting with IPF version 2.1, IntelliJ IDEA 9.0.1 or higher (Ultimate or Community Edition) is directly supported as a development platform for IPF applications and IPF source code.

Writing IPF applications

To create a new IPF application in IntelliJ IDEA choose File/New Project. Select Create project from scratch and press Next. Choose the name and directory for the project and the new module and select Maven Module from the Select Type list, e.g.:

After clicking Next you define the group and artifact ID of your new application as well as the archetype that you want to use as a project template. To use the IPF archetype ipf-archetype-basic it has to be added to IDEA first. To do so, activate Create from archetype and click Add archetype.... In the dialog that pops up specify the IDs and version for the IPF archetype (use the version number of the IPF version you want to use):

After clicking Ok, select the newly added archetype and press Finish. IDEA runs the archetype to create a new pom file and creates an IDEA project and module with the given settings. The result should look similar to the following screenshot:

You can enable the auto import of pom files in the top of the editor window by clicking on Enable Auto-Import. This allows you to automatically update the project if the pom file changes.

One of the big advantages of using IDEA is the Groovy support, especially the code completion for route builders. To demonstrate this, open the file SampleRouteBuilder.groovy and add another line to it:

transmogrify is an IPF DSL extension that is usually not recognized automatically. E.g. in Eclipse, you will not be able to get code completion for these DSL extensions. By [using the scripting interface] of the Groovy plugin in IDEA, the IPF jars automatically extend the code completion feature. You can use the same mechanism if you want to enable code completion for your own model extensions.

Working with the source code of the IPF

If you checked out the source code of the IPF you can also create an IDEA project for it. To do so, create a new project using File/New Project, select Import project from external model and click Next. Choose Maven from the list and click Next. In the next dialog you define the Root directory to be the check-out location of the IPF sources. Make sure that the option Create IDEA modules for aggregator projects (with 'pom' packaging) is disabled. You will get irritating warnings when Rebuilding the project otherwise. All other options can be choosen to your liking, e.g.:

Click Next, select the Maven profile that you want to use (usually openehealth):

On the next page the main artifact of the IPF should be selected:

Now you need to configure the JDK. You can add an installed JDK to the list by clicking on the small + and selecting JSDK. Choose the directory of your JDK installation and press Ok:

Finally you can choose the name of the new IDEA project and the location of the project files and click Finish. Importing the files and updating all the dependencies will take a while, because the IPF contains quite a number of modules that require various dependencies. After the import you can ignore projects in the Maven Projects view depending on what you are working with. You should at least ignore ipf-archetypes and ipf-archetype-basic. IDEA will not treat the Java and Groovy files in these projects as if they were normal source files. However, they are template files and do not contain valid source code. Therefore, it is best to ignore or remove these projects in the Maven Projects view. Note that removing them, does not delete them on disk. The following is screenshot of the final project: