org.meeuw.i18n:i18n-regions-parent
= geographical regions :toc:
//image:https://travis-ci.com/mihxil/i18n-regions.svg?[Build Status,link=https://travis-ci.com/mihxil/i18n-regions] image:https://github.com/mihxil/i18n-regions/workflows/build/badge.svg?[Build Status,link=https://github.com/mihxil/i18n-regions/actions?query=workflow%3Abuild] image:https://img.shields.io/maven-central/v/org.meeuw.i18n/i18n-regions.svg?label=Maven%20Central[Maven Central,link=https://search.maven.org/search?q=g:%22org.meeuw.i18n%22] image:https://img.shields.io/nexus/s/https/oss.sonatype.org/org.meeuw.i18n/i18n-regions.svg[snapshots,link=https://oss.sonatype.org/content/repositories/snapshots/org/meeuw/i18n/] image:https://www.javadoc.io/badge/org.meeuw.i18n/i18n-regions.svg?color=blue[javadoc,link=https://www.javadoc.io/doc/org.meeuw.i18n/] image:https://codecov.io/gh/mihxil/i18n-regions/branch/main/graph/badge.svg[codecov,link=https://codecov.io/gh/mihxil/i18n-regions]
== Introduction
This project was started to be able to make better use of https://github.com/TakahikoKawasaki/nv-i18n/blob/master/src/main/java/com/neovisionaries/i18n/CountryCode.java[`CountryCode`]'s from https://github.com/TakahikoKawasaki/nv-i18n[nv-i18n]
Using CountryCode as a value in your application has several drawbacks:
. It is not extensible. If you need a value not in that enum, you're stuck. . 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'. . 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 link:i18n-regions/src/main/java/org/meeuw/i18n/regions/Region.java[org.meeuw.i18n.regions.Region], which represents some geographical region.
Instances are created via https://www.baeldung.com/java-spi[java service providers] implementing link:i18n-regions/src/main/java/org/meeuw/i18n/regions/spi/RegionProvider.java[org.meeuw.i18n.regions.spi.RegionProvider] (registered via link:i18n-regions/src/main/resources/META-INF/services/org.meeuw.i18n.regions.spi.RegionProvider[META-INF/services]), which are all managed by link:i18n-regions/src/main/java/org/meeuw/i18n/regions/RegionService.java[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 https://search.maven.org/search?q=g:org.meeuw.i18n%20AND%20a:i18n-regions-countries&core=gav[`org.meeuw.i18n:i18n-regions-countries`]
It provides:
org.meeuw.i18n.countries.CurrentCountry]s. Backed by com.neovisionaries.i18n.CountryCodeorg.meeuw.i18n.countries.FormerCountry], which is backed by org.meeuw.i18n.formerlyassigned.FormerlyAssignedCountryCode (from https://github.com/mihxil/i18n-formerly-assigned[i18n-formerly-assigned])org.meeuw.i18.countries.UserAssignedCountry]all countries implement an interface link:i18n-regions-countries/src/main/java/org/meeuw/i18n/countries/Country.java[org.meeuw.i18n.countries.Country]
// 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 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 https://search.maven.org/search?q=g:org.meeuw.i18n%20AND%20a:i18n-regions-subdivisions&core=gav[`org.meeuw.i18n:i18n-regions-subdivisions`]
org.meeuw.i18n.subdivisions.CountrySubdivision], which is backed by
org.meeuw.i18n.subdivision.subdivision.CountryCodeSubdivision (from https://github.com/mihxil/i18n-subdivisions)subdivision.<country code>.properties. (E.g. this used to be the case for GB, link:i18n-regions-subdivisions/src/main/resources/org/meeuw/i18n/subdivisions/subdivisions.GB.properties[subdivisions.GB.properties] provides some which were obviously missing from Great Britain otherwise)=== Continents
A list of codes for the continents is provided in https://search.maven.org/search?q=g:org.meeuw.i18n%20AND%20a:i18n-regions-continents&core=ga[`org.meeuw.i18n:i18n-regions-continents`]
// stream all available continents:
=== More
In the same fashion arbitrary region implementations can easily be plugged in. This project also provides link:i18n-regions-openlocationcode[a region implementation based on google's 'open location code'].
== Persistence
link:i18n-regions/src/main/java/org/meeuw/i18n/regions/persistence/RegionToStringConverter.java[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.
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:
== 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.
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:
(For completeness also link:i18n-regions/src/main/java/org/meeuw/i18n/regions/validation/Language.java[@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 https://www.baeldung.com/project-jigsaw-java-modularity[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 link:src/test[src/test], in the link:tests[tests] folder I collect some sample projects to test this stuff out by hand. Try e.g.
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.
There are very few log events, it is not important.
== Release notes Release notes can be found link:RELEASE-NOTES.adoc[here].
== Testing and JPMS Find my findings link:TESTING-WITH-JPMS.adoc[here]
== Versions
|=== |Version | |
|1.x |javax, java 8 (though with module-info) | ≤ 2024
| 2.x | jakarta, java 11 | ≥ 2024 |===
FAQs
Provides wrappers around ISO-codes for geographical regions
We found that org.meeuw.i18n:i18n-regions-parent demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.