Appendix A - IPF development

Environment

Java

IPF currently requires Java SE 6 for both compile time and runtime (but we're also working on a version that runs on Java SE 5). 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 Eclipse 3.4 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). Here is an example eclipse.ini file with a -vm option. Make sure that the path to the IDE-defined JRE is a path to the corresponding JDK.

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/branches/ipf-1.7 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/branches/ipf-1.7 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 1.7 development branch 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.

Figure: IPF Platform Manager 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). Please note that the Maven build for the platform-manager Eclipse plugins (org.openehealth.ipf.platform.manager.* components) isn't a replacement for the build mechanisms of the Eclipse platform. You still need to import these plugins into Eclipse for building the Integration Platform Manager and for creating an executable Eclipse RCP application.

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 (except the Eclipse-based Integration Platform Manager).

<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.

Platform manager

The Integration Platform Manager (org.openehealth.ipf.platform.manager.* components) is an Eclipse RCP application that can be either started from within the Eclipse IDE or standalone after having created an application package. Double-click on the platform-manager-win32-eclipse-3.4.1.product file in the org.openehealth.ipf.platform.manager.application project. In the tab that opens in the editor pane, click on the Launch an Eclipse application link to start the Integration Platform Manager or click on the Eclipse product export wizard to create an executable application package.

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=1.7.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.