geographical regions

Table of Contents

• Introduction
• Architecture
• Providers
  • Countries
  • Subdivisions of countries
  • Continents
  • More
• Persistence
• XML Binding
• Translations
• Validation
• Optional dependencies
• Building and Jigsaw
• Testing
• Logging
• Release notes
• Testing and JPMS
• Versions

Introduction

This project was started to be able to make better use of CountryCode's from nv-i18n

Using CountryCode as a value in your application has several drawbacks:

1. It is not extensible. If you need a value not in that enum, you’re stuck.

2. It for example does not contain 'former countries', so e.g. the birth country of a person, or the country of a movie cannot be stored as a 'CountryCode'.

3. It’s only applicable to countries, no other regions.

I decided to wrap CountryCode in a class CurrentCountry, which implements a Region interface (actually it implements the Country extension) , which makes it possible to make other implementations of Region too, and to address all the above issues. You have to use Region (or Country) instead of CountryCode as the type of your variable then.

Architecture

The central interface of this module is org.meeuw.i18n.regions.Region, which represents some geographical region.

Instances are created via java service providers implementing org.meeuw.i18n.regions.spi.RegionProvider (registered via META-INF/services), which are all managed by org.meeuw.i18n.regions.RegionService.

Providers are distributed via different artifacts, so you can in that way select what kind of regions the service should provide.

Providers

Countries

If you only need countries, you can take a dependency on org.meeuw.i18n:i18n-regions-countries

It provides:

• For current countries there are org.meeuw.i18n.countries.CurrentCountrys. Backed by com.neovisionaries.i18n.CountryCode

• For former countries there is org.meeuw.i18n.countries.FormerCountry, which is backed by org.meeuw.i18n.formerlyassigned.FormerlyAssignedCountryCode (from i18n-formerly-assigned)

• Some common user assigned countries are hard coded in org.meeuw.i18.countries.UserAssignedCountry

all countries implement an interface org.meeuw.i18n.countries.Country

Example code

// get one country
CurrentCountry netherlands = org.meeuw.i18n.regions.RegionService.getInstance().getByCode("NL", CurrentCountry.class).orElseThrow();
com.neovisionaries.i18n.CountryCode code = netherlands.getCode();

// link to flag image:
Optional<URI> icon = netherlands.getIcon();

String nameInLocalLanguage = netherlands.getLocalName();


// stream all available countries:

Stream<? extends Region> values = org.meeuw.i18n.regions.RegionService.getInstance().values(Region.Type.COUNTRY);

Note	It is possible that https://github.com/TakahikoKawasaki/nv-i18n becomes abandoned. In that case we might create a new enum for all codes. May be it can be auto created using online resources. Or we use the list provided in java 9’s java.util.Locale.

Subdivisions of countries

These are provided in org.meeuw.i18n:i18n-regions-subdivisions

• For subdivision of countries org.meeuw.i18n.subdivisions.CountrySubdivision, which is backed by org.meeuw.i18n.subdivision.subdivision.CountryCodeSubdivision (from https://github.com/mihxil/i18n-subdivisions)

• In case there are missing country subdivision they can easily be added via subdivision.<country code>.properties. (E.g. this used to be the case for GB, subdivisions.GB.properties provides some which were obviously missing from Great Britain otherwise)

Continents

A list of codes for the continents is provided in org.meeuw.i18n:i18n-regions-continents

Example code

// stream all available continents:

Stream<? extends Continent> values = org.meeuw.i18n.regions.RegionService.getInstance().values(Continent.class);
assertThat(values).hasSize(7);

More

In the same fashion arbitrary region implementations can easily be plugged in. This project also provides a region implementation based on google’s 'open location code'.

Persistence

org.meeuw.i18n.regions.persistence.RegionToStringConverter is meant to arrange JPA persistence of Region objects to the database. We want the iso code to be used as simple strings in a database column or so.

This will also deal gracefully with codes which gets unassigned, because RegionService#getByCode will also fall back to formerly assigned codes.

e.g.

@ElementCollection
@Convert(converter = RegionToStringConverter.class)
protected List<org.meeuw.i18n.regions.Region> countries;

The converter is marked as autoApply, so in principle it is not needed to add this @Convert annotation explicitely, if this converter is available in your persistence.xml. Or e.g. its equivalent like this:

@EntityScan(basePackages = { ...}, basePackageClasses = {org.meeuw.i18n.regions.persistence.RegionToStringConverter.class})

XML Binding

The Region interface is JAXB-annotated to be marshallable to XML, which obviously should happen by the (ISO) code string. This can also be used for json.

Translations

The region interface also provides Region#getName(Locale) to retrieve the name of the region in the given locale. For many countries/locales this is supported by the JVM. Missing values can be provided via the Regions resource bundle.

Validation

Given a certain field with type Region (or one of its subtypes) you may still find that makes too many values available. Therefore, we also provide some javax.validation.ConstraintValidator and associated annotations to limit possible values.

e.g.

protected List<
        // valid are countries (further validated by @ValidCountry), and a list of codes.
   org.meeuw.i18n.regions.
        @ValidRegion(classes = {Country.class}, includes = {"GB-ENG", "GB-NIR", "GB-SCT", "GB-WLS"})
        @ValidCountry(value = ValidCountry.OFFICIAL | ValidCountry.USER_ASSIGNED | ValidCountry.FORMER, excludes = {"XN"})
        @NotNull Region> countries;

or, if you prefer, on the collection itself:

    @ValidCountry(value = ValidCountry.OFFICIAL | ValidCountry.USER_ASSIGNED | ValidCountry.FORMER, includes = {"GB-ENG", "GB-NIR", "GB-SCT", "GB-WLS"})
    protected List<org.meeuw.i18n.regions.Region> countries;

This list will not validate if you add Regions which don’t follow the given rules.

It can also be used on java.util.Locale, which contains a country component too:

 protected List<
        @ValidRegion(classes = {Country.class})
        @ValidCountry(value = ValidCountry.OFFICIAL | ValidCountry.USER_ASSIGNED | ValidCountry.FORMER, excludes = {"XN"})
        @Language(mayContainCountry = true)
        @NotNull Locale> languages;

(For completeness also @Language is provided).

As a utility, there is org.meeuw.i18n.regions.validation.RegionValidatorService which can be used to filter a stream of regions (e.g. RegionService#values()) based on the settings of these annotations.

 // A list of all valid regions for the property 'countries' of the 'MediaObject'
 return RegionService.getInstance().values()
            .filter(RegionValidatorService.getInstance().fromProperty(MediaObject.class, "countries"))
            .sorted(Regions.sortByName(LanguageCode.nl));

Optional dependencies

Several dependencies are marked optional in the pom.xml. E.g. the annotations used to arrange XML bindings and validation are not present (anymore) in java 11. If they are not present, this will not make it impossible to use the classes, you just cannot use JAXB, JPA, validation or whatever the missing dependency is related to. It’s only about annotations so that doesn’t cause (by the JSR-175 specification) problems.

Building and Jigsaw

This projects needs to build with java 11. It produces byte code compatible for java 8 though (besides module-info.class) The goal is to be compatible with jigsaw, which was introduced in java 9.

If you use java 11 then you can require org.meeuw.i18n.regions in module-info.java.

Testing

Besides the usual junit test in src/test, in the tests folder I collect some sample projects to test this stuff out by hand. Try e.g.

cd tests/springboot
mvn spring-boot:run

There are also tests in 'blackbox-testing'. Mainly testing validation code (because JPMS).

To achieve a proper report of test coverage the module 'report-aggregation' just depends on everything together witht some jacoco plugin configuration.

Logging

Some logging happens via the java.util.logging framework to avoid any extra dependencies.

When you use slf4j or logback or so you could take a dependency to catch such logging in your logging framework of choice.

<dependency>
  <!-- region service uses java.util.logging. This makes it log to logback as springboot does -->
  <groupId>org.slf4j</groupId>
  <artifactId>jul-to-slf4j</artifactId>
  <version>1.7.25</version>
</dependency>

There are very few log events, it is not important.

Release notes

Release notes can be found here.

Testing and JPMS

Find my findings here

Versions

Version
1.x	javax, java 8 (though with module-info)	≤ 2024
2.x	jakarta, java 11	≥ 2024
2.2	deprecating use of neovisionaries for languages, in favour of org.meeuw.i18n:i18n-iso-639	july 2024
2.3	deprecating use of neovisionaries for current countries. Just scrape them from wikipedia or so	TODO ?
3.x	drop dependency on neovisionaries	TODO ?