Introduction
This page describes how the OpenNCP Protocol Terminator common component can be integrated with the National Connector (NC).
Background
Each country has their own implementation of the National Connector and therefore the way that OpenNCP connects with the NC will be different for each country. Therefore it is necessary to “inject” country-specific functionality into the Protocol Terminator.
Implementation
The following diagram shows the relevant OpenNCP classes and the classes that are country-specific.
Injection of the National implementation classes is handled by a ServiceLoader. The ServiceLoader will locate and load a specific implementation (called a Service Provider) of an interface. The ServiceLoader is included in Java SE6 and is already utilized in OpenNCP.
Here is an example that shows the ServiceLoader in action. Here you can see how an implementation of the PatientSearchInterface is loaded.
public class XCPDServiceImpl implements XCPDServiceInterface {
private ServiceLoader<PatientSearchInterface> serviceLoader;
private PatientSearchInterface patientSearchService;
public XCPDServiceImpl() {
serviceLoader = ServiceLoader.load(PatientSearchInterface.class);
try {
logger.info("Loading National implementation of PatientSearchInterface...");
patientSearchService = serviceLoader.iterator().next();
logger.info("Successfully loaded PatientSearchService");
} catch (ServiceConfigurationError e) {
logger.fatal("Exception loading PatientSearchService: ", e);
}
}
}
Note that the loader is initialized with an interface type. The loader will search for a provider-configuration file in the resource directory META-INF/services. The file's name is the same as the interface name. The file contains the fully-qualified name of the concrete provider class.
Example of provider-configuration file containing Swedish configuration:
eu.epsos.protocolterminators.ws.server.xcpd.PatientSearchInterface
se.sb.epsos.shelob.ws.server.xcpd.impl.PatientSearchImpl
Mock implementations
Mock implementations of the DocumentSubmitImpl, DocumentSearchImpl and PatientSearchImpl are provided in the project epsos-ws-server-mock-impl. These classes simply return dummy responses (not implemented yet). The mock implementations are packaged as a jar file epsos-ws-server-mock-impl-0.1.0.jar.
Packaging
Each country must build their own jar file containing their own implementations, dependencies and supporting files.
This National jar file can be bundled into the epsos-ws-server.war if desired. The pom.xml for the epsos-ws-server project uses profiles to achieve this goal. Maven profiles enable portable build scripts that can be run with with different configurations.
<profiles>
<profile>
<!-- This profile bundles a mock National Connector interface -->
<id>national-connector-mock-impl</id>
<dependencies>
<dependency>
<groupId>eu.epsos.protocolterminators.ws.server</groupId>
<artifactId>epsos-ws-server-mock-impl</artifactId>
<version>0.1.0</version>
<scope>runtime</scope>
</dependency>
</dependencies>
</profile>
<profile>
<!-- This profile bundles the country-specifig National Connector interface -->
<id>national-connector-impl</id>
<dependencies>
<dependency>
<groupId>${national-connector-impl.groupId}</groupId>
<artifactId>${national-connector-impl.artifactId}</artifactId>
<version>${national-connector-impl.version}</version>
<scope>runtime</scope>
</dependency>
</dependencies>
</profile>
</profiles>
The first profile bundles the mock implementations into the war file. The second profile bundles a National implementation. If no profile is specified then no implementation will be bundled at all. In this case, the jar must be deployed to the tomcat/lib directory.
The National profile needs some properties. These properties are defined in the local build environment:
Per User
- Defined in the Maven-settings (%USER_HOME%/.m2/settings.xml).
Global
- Defined in the global Maven-settings (%M2_HOME%/conf/settings.xml).
Profile descriptor
- a descriptor located in project basedir (profiles.xml) (unsupported in Maven 3.x)
Example settings.xml for Sweden:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
<profiles>
<profile>
<id>national-connector-impl</id>
<properties>
<national-connector-impl.groupId>se.apotekensservice</national-connector-impl.groupId>
<national-connector-impl.artifactId>epsos-shelob</national-connector-impl.artifactId>
<national-connector-impl.version>0.0.1-SNAPSHOT</national-connector-impl.version>
</properties>
</profile>
</profiles>
</settings>
Here are the Maven commands:
# build epsos-ws-serverwith no implementation mvn clean install # build epsos-ws-server with mock implementations mvn clean install -P national-connector-mock-impl # build epsos-ws-server with real implementations mvn clean install -P national-connector-impl
Example National build script
Here is the Maven pom that Sweden uses to download OpenNCP from Joinup Nexus repository and then bundle in the jar containing the National implementations.
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<artifactId>epsos</artifactId>
<groupId>se.apotekensservice</groupId>
<version>1.0-SNAPSHOT</version>
</parent>
<groupId>se.apotekensservice</groupId>
<artifactId>epsos-ncp</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>war</packaging>
<name>Package OpenNCP</name>
<description>This project fetches the OpenNCP epsos-ws-server.war. It then unpacks it, adds the shelob.jar dependency and creates a new web archive</description>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.5.1</version>
<executions>
<execution>
<id>unpack</id>
<phase>package</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>${project.openNcpGroupId}</groupId>
<artifactId>${project.openNcpArtifactId}</artifactId>
<version>${project.openNcpVersion}</version>
<type>war</type>
<overWrite>true</overWrite>
<outputDirectory>${project.build.directory}/epsos-ws-server</outputDirectory>
<includes></includes>
<excludes>epsos-ws-server-mock*.jar</excludes>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
<dependencies>
<dependency>
<groupId>${project.shelobGroupId}</groupId>
<artifactId>${project.shelobArtifactId}</artifactId>
<version>${project.shelobVersion}</version>
</dependency>
<dependency>
<groupId>${project.openNcpGroupId}</groupId>
<artifactId>${project.openNcpArtifactId}</artifactId>
<version>${project.openNcpVersion}</version>
<type>war</type>
</dependency>
</dependencies>
<properties>
<!-- OpenNCP war -->
<project.openNcpGroupId>eu.europa.ec.joinup.ecc.epsos-protocol-terminators.epsos-ncp-server</project.openNcpGroupId>
<project.openNcpArtifactId>epsos-ws-server</project.openNcpArtifactId>
<project.openNcpVersion>0.2.1-SNAPSHOT</project.openNcpVersion>
<!-- Shelob jar -->
<project.shelobGroupId>se.apotekensservice</project.shelobGroupId>
<project.shelobArtifactId>epsos-shelob</project.shelobArtifactId>
<project.shelobVersion>0.0.1-SNAPSHOT</project.shelobVersion>
</properties>
</project>
References
ServiceLoader tutorial at java.net