[#252] Support for 'addresshierarchy' domain.

README.md

@@ -121,6 +121,7 @@ This is the list of currently supported domains in their loading order:
 1. [Provider Roles (CSV files)](readme/providerroles.md)
 1. [Locations (CSV files)](readme/loc.md)
 1. [Location Tag Maps (CSV files)](readme/loctagmaps.md)
+1. [Address Hierarchy (XML, CSV, .properties files)](readme/addresshierarchy.md)
 1. [Bahmni Forms (JSON Files)](readme/bahmniforms.md)
 1. [Concept Classes (CSV files)](readme/conceptclasses.md)
 1. [Concept Sources (CSV files)](readme/conceptsources.md)
@@ -195,6 +196,7 @@ See the [documentation on Initializer's logging properties](readme/rtprops.md#lo
 
 #### Version 2.7.0
 * Added support for 'queues' domain.
+* Added support for 'addresshierarchy' domain.
 
 #### Version 2.6.0
 * Added support for 'cohorttypes' and 'cohortattributetypes' domains.

api/src/main/java/org/openmrs/module/initializer/Domain.java

@@ -21,6 +21,7 @@ public enum Domain {
 	PROVIDER_ROLES,
 	LOCATIONS,
 	LOCATION_TAG_MAPS,
+	ADDRESS_HIERARCHY,
 	BAHMNI_FORMS,
 	OCL,
 	CONCEPTS,

api/src/main/java/org/openmrs/module/initializer/api/loaders/AddressHierarchyLoader.java

@@ -0,0 +1,42 @@
+package org.openmrs.module.initializer.api.loaders;
+
+import java.nio.file.Paths;
+import java.util.List;
+
+import org.openmrs.annotation.OpenmrsProfile;
+import org.openmrs.module.addresshierarchy.config.AddressConfigurationLoader;
+import org.openmrs.module.initializer.Domain;
+import org.openmrs.module.initializer.api.ConfigDirUtil;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+@OpenmrsProfile(modules = { "addresshierarchy:2.17.* - 9.*" })
+public class AddressHierarchyLoader extends BaseLoader {
+
+	protected final Logger log = LoggerFactory.getLogger(getClass());
+
+	@Override
+	protected Domain getDomain() {
+		return Domain.ADDRESS_HIERARCHY;
+	}
+
+	@Override
+	public ConfigDirUtil getDirUtil() {
+		return new ConfigDirUtil(iniz.getConfigDirPath(), iniz.getChecksumsDirPath(), getDomainName(), true);
+	}
+
+	@Override
+	public void loadUnsafe(List<String> wildcardExclusions, boolean doThrow) throws Exception {
+
+		try {
+			AddressConfigurationLoader.loadAddressConfiguration(Paths.get(iniz.getConfigDirPath()), Paths.get(iniz.getChecksumsDirPath()));
+		}
+		catch (Exception e) {
+			log.error(e.getMessage());
+			if (doThrow) {
+				log.error("The loading of the '" + getDomainName() + "' configuration was aborted.", e);
+				throw new RuntimeException(e);
+			}
+		}
+	}
+}

api/src/test/java/org/openmrs/module/initializer/DomainBaseModuleContextSensitiveTest.java

@@ -66,6 +66,11 @@ public InitializerService getService() {
 	 */
 	public DomainBaseModuleContextSensitiveTest() {
 		super();
+		{
+			Module mod = new Module("", "exti18n", "", "", "", "1.0.0");
+			mod.setFile(new File(""));
+			ModuleFactory.getStartedModulesMap().put(mod.getModuleId(), mod);
+		}
 		{
 			Module mod = new Module("", "fhir2", "", "", "", "1.6.0");
 			mod.setFile(new File(""));

api/src/test/java/org/openmrs/module/initializer/AddressHierarchyMessagesLoadingTest.java → api/src/test/java/org/openmrs/module/initializer/api/AddressHierarchyLoaderIntegrationTest.java

@@ -7,7 +7,7 @@
  * Copyright (C) OpenMRS Inc. OpenMRS is a registered trademark and the OpenMRS
  * graphic logo is a trademark of OpenMRS Inc.
  */
-package org.openmrs.module.initializer;
+package org.openmrs.module.initializer.api;
 
 import java.io.File;
 import java.io.FileReader;
@@ -23,7 +23,6 @@
 import org.junit.After;
 import org.junit.Assert;
 import org.junit.Before;
-import org.junit.Ignore;
 import org.junit.Test;
 import org.openmrs.GlobalProperty;
 import org.openmrs.PersonAddress;
@@ -38,13 +37,18 @@
 import org.openmrs.module.addresshierarchy.config.AddressConfigurationLoader;
 import org.openmrs.module.addresshierarchy.service.AddressHierarchyService;
 import org.openmrs.module.exti18n.ExtI18nConstants;
+import org.openmrs.module.exti18n.api.AddressHierarchyI18nCache;
+import org.openmrs.module.initializer.DomainBaseModuleContextSensitiveTest;
+import org.openmrs.module.initializer.InitializerConfig;
+import org.openmrs.module.initializer.InitializerConstants;
+import org.openmrs.module.initializer.InitializerMessageSource;
 import org.openmrs.module.initializer.api.InitializerService;
+import org.openmrs.module.initializer.api.loaders.AddressHierarchyLoader;
 import org.openmrs.test.Verifies;
 import org.openmrs.util.OpenmrsConstants;
 import org.springframework.beans.factory.annotation.Autowired;
 
-@Ignore
-public class AddressHierarchyMessagesLoadingTest extends DomainBaseModuleContextSensitiveTest {
+public class AddressHierarchyLoaderIntegrationTest extends DomainBaseModuleContextSensitiveTest {
 
 	protected static final String MODULES_TO_LOAD = "org/openmrs/module/addresshierarchy/include/"
 	        + ExtI18nConstants.MODULE_ARTIFACT_ID + ".omod";
@@ -54,14 +58,17 @@ public class AddressHierarchyMessagesLoadingTest extends DomainBaseModuleContext
 	@Autowired
 	protected InitializerConfig cfg;
 
+	@Autowired
+	private AddressHierarchyLoader loader;
+
 	@Before
 	public void setup() {
 		// Disabling AH full caching otherwise loading takes too long
 		Context.getAdministrationService().saveGlobalProperty(new GlobalProperty(
 		        AddressHierarchyConstants.GLOBAL_PROP_INITIALIZE_ADDRESS_HIERARCHY_CACHE_ON_STARTUP, "false"));
 
-		Context.getAdministrationService()
-		        .saveGlobalProperty(new GlobalProperty(OpenmrsConstants.GLOBAL_PROPERTY_LOCALE_ALLOWED_LIST, "en, km_KH"));
+		Context.getAdministrationService().saveGlobalProperty(
+		    new GlobalProperty(OpenmrsConstants.GLOBAL_PROPERTY_LOCALE_ALLOWED_LIST, "en_GB, km_KH"));
 
 		Context.getAdministrationService()
 		        .saveGlobalProperty(new GlobalProperty(ExtI18nConstants.GLOBAL_PROP_REV_I18N_SUPPORT, "true"));
@@ -84,10 +91,9 @@ public void tearDown() {
 	public void refreshCache_shouldLoadAddressHierarchyMessages() throws IOException {
 
 		// Replay
+		loader.load();
 		AddressConfigurationLoader.loadAddressConfiguration();
-
 		AddressHierarchyService ahs = Context.getService(AddressHierarchyService.class);
-		ahs.initI18nCache();
 		InitializerService iniz = Context.getService(InitializerService.class);
 
 		File csvFile = new File(
@@ -106,6 +112,8 @@ public void refreshCache_shouldLoadAddressHierarchyMessages() throws IOException
 		address.setCountyDistrict("ច្បារមន");
 		address.setAddress1("សុព័រទេព");
 
+		AddressHierarchyI18nCache ahI18nCache = Context.getRegisteredComponent(ExtI18nConstants.COMPONENT_AH_REVI18N,
+		    AddressHierarchyI18nCache.class);
 		// Looking for possible villages based on an address provided in km_KH
 		AddressHierarchyLevel villageLevel = ahs.getAddressHierarchyLevelByAddressField(AddressField.CITY_VILLAGE);
 		List<AddressHierarchyEntry> villageEntries = ahs.getPossibleAddressHierarchyEntries(address, villageLevel);

pom.xml

@@ -79,7 +79,7 @@
         <serializationVersion>0.2.14</serializationVersion>
 
         <!-- For tests -->
-        <addresshierarchyVersion>2.11.0</addresshierarchyVersion>
+        <addresshierarchyVersion>2.17.0-SNAPSHOT</addresshierarchyVersion>
         <exti18nVersion>1.0.0</exti18nVersion>
         <appframeworkVersion>2.14.0</appframeworkVersion>
         <providermanagementVersion>2.13.0</providermanagementVersion>

readme/addresshierarchy.md

@@ -0,0 +1,55 @@
+## Domain 'addresshierarchy'
+The **addresshierarchy** subfolder contains configuration files expected by the Address Hierarchy module.
+
+Below is a typical content of the 'addresshierarchy' configuration subfolder:
+```bash
+addresshierarchy/
+  ├── addressConfiguration.xml
+  ├── addresshierarchy.csv
+  ├── messages_en.properties
+  └── messages_fr.properties
+```
+###### File `addresshierarchy.csv` *(mandatory)*
+
+It contains the address hierarchy entries themselves. This is typically a large file since it may contain thousands of lower level entries in a given country. Eg.:
+```csv
+Pays, Province, Commune
+Haiti,Artibonite,Anse Rouge
+Haiti,Artibonite,Desdunes
+Haiti,Artibonite,Dessalines
+...
+Haiti,Sud-Est,Marigot
+Haiti,Sud-Est,Thiotte
+```
+**NOTE:** This file may or may not contain a header row.
+
+###### File `addressConfiguration.xml` *(mandatory)*
+This file defines both:
+
+1. The [address template](https://wiki.openmrs.org/x/OgTX) and
+2. A mapping of the address template fields to the level of the address hierarchy entries that it can be populated with. This mapping occurs differently depending on whether the address level entries CSV file may or may not have a header row.
+
+**Option 1: if the address level entries CSV file has a header row**, it maps the address template fields (`field`) with the address hierachy levels (`nameMapping`) defined as headers in `addresshierarchy.csv`. Here is an example how the address template field `STATE_PROVINCE` is mapped with the address hierarchy entries provided for `Province`:
+
+```xml
+<addressComponent>
+  <field>STATE_PROVINCE</field>
+  <nameMapping>Province</nameMapping>
+  <sizeMapping>40</sizeMapping>
+  <requiredInHierarchy>true</requiredInHierarchy>
+</addressComponent>
+```
+
+**Option 2: if  the address level entries CSV file doesn't have a header row**, it maps the address template fields <u>in the order in which they are found in the address template</u>.
+
+###### I18n `.properties` files *(optional)*
+* The i18n `.properties` files are used to populate the address/location i18n cache. The messages files can be similarly defined as those loaded by the [messageproperties](readme/messageproperties.md) domain.
+
+#### Requirements
+* The [Address Hierarchy module](https://addons.openmrs.org/show/org.openmrs.module.addresshierarchy) version 2.17.0 or above must be installed.
+
+### Further examples:
+* Find out more how the Address Hierarchy module at https://wiki.openmrs.org/display/docs/Address+Hierarchy+Module
+* Find out more about the address template at https://wiki.openmrs.org/x/OgTX
+* A full configuration example at https://github.com/openmrs/ozone-distro-cambodia/tree/main/configs/openmrs_config/addresshierarchy
+* Please look at the test configuration folder for sample import files for all domains, see [here](../api/src/test/resources/testAppDataDir/configuration).