Source code

001/*
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 *     http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package org.gbif.api.vocabulary;
015
016import java.io.IOException;
017import java.util.ArrayList;
018import java.util.Collections;
019import java.util.HashSet;
020import java.util.LinkedHashMap;
021import java.util.List;
022import java.util.Map;
023import java.util.Set;
024import java.util.stream.Collectors;
025import java.util.stream.Stream;
026
027import org.apache.commons.lang3.StringUtils;
028
029import com.fasterxml.jackson.annotation.JsonValue;
030import com.fasterxml.jackson.core.JsonGenerator;
031import com.fasterxml.jackson.core.JsonParser;
032import com.fasterxml.jackson.databind.DeserializationContext;
033import com.fasterxml.jackson.databind.JsonDeserializer;
034import com.fasterxml.jackson.databind.JsonSerializer;
035import com.fasterxml.jackson.databind.SerializerProvider;
036import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
037import com.fasterxml.jackson.databind.annotation.JsonSerialize;
038import com.fasterxml.jackson.databind.deser.std.StdDeserializer;
039
040import io.swagger.v3.oas.annotations.ExternalDocumentation;
041import io.swagger.v3.oas.annotations.media.Schema;
042
043/**
044 * <p>An enumeration for all current ISO 3166-1 Alpha-2 and Alpha-3 country codes.
045 *
046 * <p>Formerly used codes are not included.
047 *
048 * <p>All unused user assigned codes (e.g. XX and QS) are mapped to the single enum USER_DEFINED.
049 *
050 * <p>Titles are taken from the ISO standard short name in all cases.
051 *
052 * <p>GBIF Regions are based on <a href="https://www.nature.com/articles/sdata20167/figures/1">IPBES regions</a>,
053 * also <a href="https://doi.org/10.5281/zenodo.3928281">available as a CSV list</a>.
054 *
055 * <p>The source for GBIF Regions is the participant entities in the GBIF Directory, which are synchronized with
056 * {@link org.gbif.api.model.registry.Node}s in the Registry.  They are <strong>also</strong> recorded here,
057 * to provide regions for countries/territories that are not GBIF members.
058 *
059 * <p>The regions follow IPBES regions, except for Antarctic territories, as there was no IPBES report for these.
060 *
061 * @see <a href="https://www.iso.org/obp/ui/#search">ISO Online Browsing Platform</a>
062 * @see <a href="https://datahub.io/core/country-codes">ISO 3166 in the Open Knowledge International database</a>
063 * @see <a href="https://en.wikipedia.org/wiki/ISO_3166">ISO 3166 on Wikipedia</a>
064 * @see <a href="https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2">ISO 3166-1 alpha2 on Wikipedia</a>
065 * @see <a href="https://en.wikipedia.org/wiki/ISO_3166-3">ISO_3166-3 on Wikipedia</a>
066 */
067/*
068 * When updating this file, remember also to update http://rs.gbif.org/vocabulary/iso/3166-1_alpha2.xml
069 * diff -i <(grep title ../rs.gbif.org/vocabulary/iso/3166-1_alpha2.xml | grep '"en"' | grep -v -e '"[A-Z][A-Z]"' -e '"[A-Z][A-Z][A-Z]"' | cut -d'"' -f 2 | sort) \
070 *         <(grep '".."' ./src/main/java/org/gbif/api/vocabulary/Country.java | cut -d'"' -f 6 | grep . | sort)
071 *
072 * And ensure the Portal's enum has the same information.  Compare with
073 * diff <(grep '".."' ./src/main/java/org/gbif/api/vocabulary/Country.java | cut -d'"' -f 2,6 | grep '"') \
074 *      <(grep '".."' ../portal16/locales/source/en-DK/enums/country.json | cut -d'"' -f 2,4)
075 *
076 * Also ensure the GbifRegions match the participant table in the Directory.
077 *
078 * TODO: deal with outdated codes from ISO_3166-3
079 */
080@Schema(
081  externalDocs = @ExternalDocumentation(
082    description = "API call to retrieve all official values.",
083    url = "https://api.gbif.org/v1/enumeration/country"
084  )
085)
086@JsonSerialize(using = Country.IsoSerializer.class)
087@JsonDeserialize(using = Country.IsoDeserializer.class)
088public enum Country {
089
090  /**
091   * Afghanistan.
092   */
093  AFGHANISTAN("AF", "AFG", 4, "Afghanistan", GbifRegion.ASIA),
094
095  /**
096   * Åland Islands.
097   */
098  ALAND_ISLANDS("AX", "ALA", 248, "Åland Islands", GbifRegion.EUROPE),
099
100  /**
101   * Albania.
102   */
103  ALBANIA("AL", "ALB", 8, "Albania", GbifRegion.EUROPE),
104
105  /**
106   * Algeria.
107   */
108  ALGERIA("DZ", "DZA", 12, "Algeria", GbifRegion.AFRICA),
109
110  /**
111   * American Samoa.
112   */
113  AMERICAN_SAMOA("AS", "ASM", 16, "American Samoa", GbifRegion.OCEANIA),
114
115  /**
116   * Andorra.
117   */
118  ANDORRA("AD", "AND", 20, "Andorra", GbifRegion.EUROPE),
119
120  /**
121   * Angola.
122   */
123  ANGOLA("AO", "AGO", 24, "Angola", GbifRegion.AFRICA),
124
125  /**
126   * Anguilla.
127   */
128  ANGUILLA("AI", "AIA", 660, "Anguilla", GbifRegion.LATIN_AMERICA),
129
130  /**
131   * Antarctica.
132   */
133  ANTARCTICA("AQ", "ATA", 10, "Antarctica", GbifRegion.ANTARCTICA),
134
135  /**
136   * Antigua and Barbuda.
137   */
138  ANTIGUA_BARBUDA("AG", "ATG", 28, "Antigua and Barbuda", GbifRegion.LATIN_AMERICA),
139
140  /**
141   * Argentina.
142   */
143  ARGENTINA("AR", "ARG", 32, "Argentina", GbifRegion.LATIN_AMERICA),
144
145  /**
146   * Armenia.
147   */
148  ARMENIA("AM", "ARM", 51, "Armenia", GbifRegion.EUROPE),
149
150  /**
151   * Aruba.
152   */
153  ARUBA("AW", "ABW", 533, "Aruba", GbifRegion.LATIN_AMERICA),
154
155  /**
156   * Australia.
157   */
158  AUSTRALIA("AU", "AUS", 36, "Australia", GbifRegion.OCEANIA),
159
160  /**
161   * Austria.
162   */
163  AUSTRIA("AT", "AUT", 40, "Austria", GbifRegion.EUROPE),
164
165  /**
166   * Azerbaijan.
167   */
168  AZERBAIJAN("AZ", "AZE", 31, "Azerbaijan", GbifRegion.EUROPE),
169
170  /**
171   * Bahamas.
172   */
173  BAHAMAS("BS", "BHS", 44, "Bahamas", GbifRegion.LATIN_AMERICA),
174
175  /**
176   * Bahrain.
177   */
178  BAHRAIN("BH", "BHR", 48, "Bahrain", GbifRegion.ASIA),
179
180  /**
181   * Bangladesh.
182   */
183  BANGLADESH("BD", "BGD", 50, "Bangladesh", GbifRegion.ASIA),
184
185  /**
186   * Barbados.
187   */
188  BARBADOS("BB", "BRB", 52, "Barbados", GbifRegion.LATIN_AMERICA),
189
190  /**
191   * Belarus.
192   */
193  BELARUS("BY", "BLR", 112, "Belarus", GbifRegion.EUROPE),
194
195  /**
196   * Belgium.
197   */
198  BELGIUM("BE", "BEL", 56, "Belgium", GbifRegion.EUROPE),
199
200  /**
201   * Belize.
202   */
203  BELIZE("BZ", "BLZ", 84, "Belize", GbifRegion.LATIN_AMERICA),
204
205  /**
206   * Benin.
207   */
208  BENIN("BJ", "BEN", 204, "Benin", GbifRegion.AFRICA),
209
210  /**
211   * Bermuda.
212   */
213  BERMUDA("BM", "BMU", 60, "Bermuda", GbifRegion.LATIN_AMERICA),
214
215  /**
216   * Bhutan.
217   */
218  BHUTAN("BT", "BTN", 64, "Bhutan", GbifRegion.ASIA),
219
220  /**
221   * Bolivia (Plurinational State of).
222   */
223  BOLIVIA("BO", "BOL", 68, "Bolivia (Plurinational State of)", GbifRegion.LATIN_AMERICA),
224
225  /**
226   * Bonaire, Sint Eustatius and Saba.
227   */
228  BONAIRE_SINT_EUSTATIUS_SABA("BQ", "BES", 535, "Bonaire, Sint Eustatius and Saba", GbifRegion.LATIN_AMERICA),
229
230  /**
231   * Bosnia and Herzegovina.
232   */
233  BOSNIA_HERZEGOVINA("BA", "BIH", 70, "Bosnia and Herzegovina", GbifRegion.EUROPE),
234
235  /**
236   * Botswana.
237   */
238  BOTSWANA("BW", "BWA", 72, "Botswana", GbifRegion.AFRICA),
239
240  /**
241   * Bouvet Island.
242   */
243  BOUVET_ISLAND("BV", "BVT", 74, "Bouvet Island", GbifRegion.ANTARCTICA),
244
245  /**
246   * Brazil.
247   */
248  BRAZIL("BR", "BRA", 76, "Brazil", GbifRegion.LATIN_AMERICA),
249
250  /**
251   * British Indian Ocean Territory.
252   */
253  BRITISH_INDIAN_OCEAN_TERRITORY("IO", "IOT", 86, "British Indian Ocean Territory", GbifRegion.ASIA),
254
255  /**
256   * Brunei Darussalam.
257   */
258  BRUNEI_DARUSSALAM("BN", "BRN", 96, "Brunei Darussalam", GbifRegion.ASIA),
259
260  /**
261   * Bulgaria.
262   */
263  BULGARIA("BG", "BGR", 100, "Bulgaria", GbifRegion.EUROPE),
264
265  /**
266   * Burkina Faso.
267   */
268  BURKINA_FASO("BF", "BFA", 854, "Burkina Faso", GbifRegion.AFRICA),
269
270  /**
271   * Burundi.
272   */
273  BURUNDI("BI", "BDI", 108, "Burundi", GbifRegion.AFRICA),
274
275  /**
276   * Cambodia.
277   */
278  CAMBODIA("KH", "KHM", 116, "Cambodia", GbifRegion.ASIA),
279
280  /**
281   * Cameroon.
282   */
283  CAMEROON("CM", "CMR", 120, "Cameroon", GbifRegion.AFRICA),
284
285  /**
286   * Canada.
287   */
288  CANADA("CA", "CAN", 124, "Canada", GbifRegion.NORTH_AMERICA),
289
290  /**
291   * Cabo Verde.
292   */
293  CAPE_VERDE("CV", "CPV", 132, "Cabo Verde", GbifRegion.AFRICA),
294
295  /**
296   * Cayman Islands.
297   */
298  CAYMAN_ISLANDS("KY", "CYM", 136, "Cayman Islands", GbifRegion.LATIN_AMERICA),
299
300  /**
301   * Central African Republic.
302   */
303  CENTRAL_AFRICAN_REPUBLIC("CF", "CAF", 140, "Central African Republic", GbifRegion.AFRICA),
304
305  /**
306   * Chad.
307   */
308  CHAD("TD", "TCD", 148, "Chad", GbifRegion.AFRICA),
309
310  /**
311   * Chile.
312   */
313  CHILE("CL", "CHL", 152, "Chile", GbifRegion.LATIN_AMERICA),
314
315  /**
316   * China.
317   */
318  CHINA("CN", "CHN", 156, "China", GbifRegion.ASIA),
319
320  /**
321   * Christmas Island.
322   */
323  CHRISTMAS_ISLAND("CX", "CXR", 162, "Christmas Island", GbifRegion.ASIA),
324
325  /**
326   * Cocos (Keeling) Islands.
327   */
328  COCOS_ISLANDS("CC", "CCK", 166, "Cocos (Keeling) Islands", GbifRegion.ASIA),
329
330  /**
331   * Colombia.
332   */
333  COLOMBIA("CO", "COL", 170, "Colombia", GbifRegion.LATIN_AMERICA),
334
335  /**
336   * Comoros.
337   */
338  COMOROS("KM", "COM", 174, "Comoros", GbifRegion.AFRICA),
339
340  /**
341   * Congo, Democratic Republic of the.
342   */
343  CONGO_DEMOCRATIC_REPUBLIC("CD", "COD", 180, "Congo, Democratic Republic of the", GbifRegion.AFRICA),
344
345  /**
346   * Congo, Republic of the.
347   */
348  CONGO("CG", "COG", 178, "Congo", GbifRegion.AFRICA),
349
350  /**
351   * Cook Islands.
352   */
353  COOK_ISLANDS("CK", "COK", 184, "Cook Islands", GbifRegion.OCEANIA),
354
355  /**
356   * Costa Rica.
357   */
358  COSTA_RICA("CR", "CRI", 188, "Costa Rica", GbifRegion.LATIN_AMERICA),
359
360  /**
361   * Côte d’Ivoire.
362   */
363  CÔTE_DIVOIRE("CI", "CIV", 384, "Côte d’Ivoire", GbifRegion.AFRICA),
364
365  /**
366   * Croatia.
367   */
368  CROATIA("HR", "HRV", 191, "Croatia", GbifRegion.EUROPE),
369
370  /**
371   * Cuba.
372   */
373  CUBA("CU", "CUB", 192, "Cuba", GbifRegion.LATIN_AMERICA),
374
375  /**
376   * Curaçao.
377   */
378  CURAÇAO("CW", "CUW", 531, "Curaçao", GbifRegion.LATIN_AMERICA),
379
380  /**
381   * Cyprus.
382   */
383  CYPRUS("CY", "CYP", 196, "Cyprus", GbifRegion.EUROPE),
384
385  /**
386   * Czechia.
387   */
388  CZECH_REPUBLIC("CZ", "CZE", 203, "Czechia", GbifRegion.EUROPE),
389
390  /**
391   * Denmark.
392   */
393  DENMARK("DK", "DNK", 208, "Denmark", GbifRegion.EUROPE),
394
395  /**
396   * Djibouti.
397   */
398  DJIBOUTI("DJ", "DJI", 262, "Djibouti", GbifRegion.AFRICA),
399
400  /**
401   * Dominica.
402   */
403  DOMINICA("DM", "DMA", 212, "Dominica", GbifRegion.LATIN_AMERICA),
404
405  /**
406   * Dominican Republic.
407   */
408  DOMINICAN_REPUBLIC("DO", "DOM", 214, "Dominican Republic", GbifRegion.LATIN_AMERICA),
409
410  /**
411   * Ecuador.
412   */
413  ECUADOR("EC", "ECU", 218, "Ecuador", GbifRegion.LATIN_AMERICA),
414
415  /**
416   * Egypt.
417   */
418  EGYPT("EG", "EGY", 818, "Egypt", GbifRegion.AFRICA),
419
420  /**
421   * El Salvador.
422   */
423  EL_SALVADOR("SV", "SLV", 222, "El Salvador", GbifRegion.LATIN_AMERICA),
424
425  /**
426   * Equatorial Guinea.
427   */
428  EQUATORIAL_GUINEA("GQ", "GNQ", 226, "Equatorial Guinea", GbifRegion.AFRICA),
429
430  /**
431   * Eritrea.
432   */
433  ERITREA("ER", "ERI", 232, "Eritrea", GbifRegion.AFRICA),
434
435  /**
436   * Estonia.
437   */
438  ESTONIA("EE", "EST", 233, "Estonia", GbifRegion.EUROPE),
439
440  /**
441   * Ethiopia.
442   */
443  ETHIOPIA("ET", "ETH", 231, "Ethiopia", GbifRegion.AFRICA),
444
445  /**
446   * Falkland Islands (Malvinas).
447   */
448  FALKLAND_ISLANDS("FK", "FLK", 238, "Falkland Islands (Malvinas)", GbifRegion.LATIN_AMERICA),
449
450  /**
451   * Faroe Islands.
452   */
453  FAROE_ISLANDS("FO", "FRO", 234, "Faroe Islands", GbifRegion.EUROPE),
454
455  /**
456   * Fiji.
457   */
458  FIJI("FJ", "FJI", 242, "Fiji", GbifRegion.OCEANIA),
459
460  /**
461   * Finland.
462   */
463  FINLAND("FI", "FIN", 246, "Finland", GbifRegion.EUROPE),
464
465  /**
466   * France.
467   */
468  FRANCE("FR", "FRA", 250, "France", GbifRegion.EUROPE),
469
470  /**
471   * French Guiana.
472   */
473  FRENCH_GUIANA("GF", "GUF", 254, "French Guiana", GbifRegion.LATIN_AMERICA),
474
475  /**
476   * French Polynesia.
477   */
478  FRENCH_POLYNESIA("PF", "PYF", 258, "French Polynesia", GbifRegion.OCEANIA),
479
480  /**
481   * French Southern Territories.
482   */
483  FRENCH_SOUTHERN_TERRITORIES("TF", "ATF", 260, "French Southern Territories", GbifRegion.ANTARCTICA),
484
485  /**
486   * Gabon.
487   */
488  GABON("GA", "GAB", 266, "Gabon", GbifRegion.AFRICA),
489
490  /**
491   * Gambia.
492   */
493  GAMBIA("GM", "GMB", 270, "Gambia", GbifRegion.AFRICA),
494
495  /**
496   * Georgia.
497   */
498  GEORGIA("GE", "GEO", 268, "Georgia", GbifRegion.EUROPE),
499
500  /**
501   * Germany.
502   */
503  GERMANY("DE", "DEU", 276, "Germany", GbifRegion.EUROPE),
504
505  /**
506   * Ghana.
507   */
508  GHANA("GH", "GHA", 288, "Ghana", GbifRegion.AFRICA),
509
510  /**
511   * Gibraltar.
512   */
513  GIBRALTAR("GI", "GIB", 292, "Gibraltar", GbifRegion.EUROPE),
514
515  /**
516   * Greece.
517   */
518  GREECE("GR", "GRC", 300, "Greece", GbifRegion.EUROPE),
519
520  /**
521   * Greenland.
522   */
523  GREENLAND("GL", "GRL", 304, "Greenland", GbifRegion.NORTH_AMERICA),
524
525  /**
526   * Grenada.
527   */
528  GRENADA("GD", "GRD", 308, "Grenada", GbifRegion.LATIN_AMERICA),
529
530  /**
531   * Guadeloupe.
532   */
533  GUADELOUPE("GP", "GLP", 312, "Guadeloupe", GbifRegion.LATIN_AMERICA),
534
535  /**
536   * Guam.
537   */
538  GUAM("GU", "GUM", 316, "Guam", GbifRegion.OCEANIA),
539
540  /**
541   * Guatemala.
542   */
543  GUATEMALA("GT", "GTM", 320, "Guatemala", GbifRegion.LATIN_AMERICA),
544
545  /**
546   * Guernsey.
547   */
548  GUERNSEY("GG", "GGY", 831, "Guernsey", GbifRegion.EUROPE),
549
550  /**
551   * Guinea.
552   */
553  GUINEA("GN", "GIN", 324, "Guinea", GbifRegion.AFRICA),
554
555  /**
556   * Guinea-Bissau.
557   */
558  GUINEA_BISSAU("GW", "GNB", 624, "Guinea-Bissau", GbifRegion.AFRICA),
559
560  /**
561   * Guyana.
562   */
563  GUYANA("GY", "GUY", 328, "Guyana", GbifRegion.LATIN_AMERICA),
564
565  /**
566   * Haiti.
567   */
568  HAITI("HT", "HTI", 332, "Haiti", GbifRegion.LATIN_AMERICA),
569
570  /**
571   * Heard Island and McDonald Islands.
572   */
573  HEARD_MCDONALD_ISLANDS("HM", "HMD", 334, "Heard Island and McDonald Islands", GbifRegion.ANTARCTICA),
574
575  /**
576   * Holy See.
577   */
578  VATICAN("VA", "VAT", 336, "Holy See", GbifRegion.EUROPE),
579
580  /**
581   * Honduras.
582   */
583  HONDURAS("HN", "HND", 340, "Honduras", GbifRegion.LATIN_AMERICA),
584
585  /**
586   * Hong Kong.
587   */
588  HONG_KONG("HK", "HKG", 344, "Hong Kong", GbifRegion.ASIA),
589
590  /**
591   * Hungary.
592   */
593  HUNGARY("HU", "HUN", 348, "Hungary", GbifRegion.EUROPE),
594
595  /**
596   * Iceland.
597   */
598  ICELAND("IS", "ISL", 352, "Iceland", GbifRegion.EUROPE),
599
600  /**
601   * India.
602   */
603  INDIA("IN", "IND", 356, "India", GbifRegion.ASIA),
604
605  /**
606   * Indonesia.
607   */
608  INDONESIA("ID", "IDN", 360, "Indonesia", GbifRegion.ASIA),
609
610  /**
611   * Iran (Islamic Republic of).
612   */
613  IRAN("IR", "IRN", 364, "Iran (Islamic Republic of)", GbifRegion.ASIA),
614
615  /**
616   * Iraq.
617   */
618  IRAQ("IQ", "IRQ", 368, "Iraq", GbifRegion.ASIA),
619
620  /**
621   * Ireland.
622   */
623  IRELAND("IE", "IRL", 372, "Ireland", GbifRegion.EUROPE),
624
625  /**
626   * Isle of Man.
627   */
628  ISLE_OF_MAN("IM", "IMN", 833, "Isle of Man", GbifRegion.EUROPE),
629
630  /**
631   * Israel.
632   */
633  ISRAEL("IL", "ISR", 376, "Israel", GbifRegion.EUROPE),
634
635  /**
636   * Italy.
637   */
638  ITALY("IT", "ITA", 380, "Italy", GbifRegion.EUROPE),
639
640  /**
641   * Jamaica.
642   */
643  JAMAICA("JM", "JAM", 388, "Jamaica", GbifRegion.LATIN_AMERICA),
644
645  /**
646   * Japan.
647   */
648  JAPAN("JP", "JPN", 392, "Japan", GbifRegion.ASIA),
649
650  /**
651   * Jersey.
652   */
653  JERSEY("JE", "JEY", 832, "Jersey", GbifRegion.EUROPE),
654
655  /**
656   * Jordan.
657   */
658  JORDAN("JO", "JOR", 400, "Jordan", GbifRegion.ASIA),
659
660  /**
661   * Kazakhstan.
662   */
663  KAZAKHSTAN("KZ", "KAZ", 398, "Kazakhstan", GbifRegion.EUROPE),
664
665  /**
666   * Kenya.
667   */
668  KENYA("KE", "KEN", 404, "Kenya", GbifRegion.AFRICA),
669
670  /**
671   * Kiribati.
672   */
673  KIRIBATI("KI", "KIR", 296, "Kiribati", GbifRegion.OCEANIA),
674
675  /**
676   * Korea (Democratic People’s Republic of).
677   */
678  KOREA_NORTH("KP", "PRK", 408, "Korea (Democratic People’s Republic of)", GbifRegion.ASIA),
679
680  /**
681   * Korea, Republic of.
682   */
683  KOREA_SOUTH("KR", "KOR", 410, "Korea, Republic of", GbifRegion.ASIA),
684
685  /**
686   * Kuwait.
687   */
688  KUWAIT("KW", "KWT", 414, "Kuwait", GbifRegion.ASIA),
689
690  /**
691   * Kyrgyzstan.
692   */
693  KYRGYZSTAN("KG", "KGZ", 417, "Kyrgyzstan", GbifRegion.EUROPE),
694
695  /**
696   * Lao People’s Democratic Republic.
697   */
698  LAO("LA", "LAO", 418, "Lao People’s Democratic Republic", GbifRegion.ASIA),
699
700  /**
701   * Latvia.
702   */
703  LATVIA("LV", "LVA", 428, "Latvia", GbifRegion.EUROPE),
704
705  /**
706   * Lebanon.
707   */
708  LEBANON("LB", "LBN", 422, "Lebanon", GbifRegion.ASIA),
709
710  /**
711   * Lesotho.
712   */
713  LESOTHO("LS", "LSO", 426, "Lesotho", GbifRegion.AFRICA),
714
715  /**
716   * Liberia.
717   */
718  LIBERIA("LR", "LBR", 430, "Liberia", GbifRegion.AFRICA),
719
720  /**
721   * Libya.
722   */
723  LIBYA("LY", "LBY", 434, "Libya", GbifRegion.AFRICA),
724
725  /**
726   * Liechtenstein.
727   */
728  LIECHTENSTEIN("LI", "LIE", 438, "Liechtenstein", GbifRegion.EUROPE),
729
730  /**
731   * Lithuania.
732   */
733  LITHUANIA("LT", "LTU", 440, "Lithuania", GbifRegion.EUROPE),
734
735  /**
736   * Luxembourg.
737   */
738  LUXEMBOURG("LU", "LUX", 442, "Luxembourg", GbifRegion.EUROPE),
739
740  /**
741   * Macao.
742   */
743  MACAO("MO", "MAC", 446, "Macao", GbifRegion.ASIA),
744
745  /**
746   * North Macedonia.
747   */
748  MACEDONIA("MK", "MKD", 807, "North Macedonia", GbifRegion.EUROPE),
749
750  /**
751   * Madagascar.
752   */
753  MADAGASCAR("MG", "MDG", 450, "Madagascar", GbifRegion.AFRICA),
754
755  /**
756   * Malawi.
757   */
758  MALAWI("MW", "MWI", 454, "Malawi", GbifRegion.AFRICA),
759
760  /**
761   * Malaysia.
762   */
763  MALAYSIA("MY", "MYS", 458, "Malaysia", GbifRegion.ASIA),
764
765  /**
766   * Maldives.
767   */
768  MALDIVES("MV", "MDV", 462, "Maldives", GbifRegion.ASIA),
769
770  /**
771   * Mali.
772   */
773  MALI("ML", "MLI", 466, "Mali", GbifRegion.AFRICA),
774
775  /**
776   * Malta.
777   */
778  MALTA("MT", "MLT", 470, "Malta", GbifRegion.EUROPE),
779
780  /**
781   * Marshall Islands.
782   */
783  MARSHALL_ISLANDS("MH", "MHL", 584, "Marshall Islands", GbifRegion.OCEANIA),
784
785  /**
786   * Martinique.
787   */
788  MARTINIQUE("MQ", "MTQ", 474, "Martinique", GbifRegion.LATIN_AMERICA),
789
790  /**
791   * Mauritania.
792   */
793  MAURITANIA("MR", "MRT", 478, "Mauritania", GbifRegion.AFRICA),
794
795  /**
796   * Mauritius.
797   */
798  MAURITIUS("MU", "MUS", 480, "Mauritius", GbifRegion.AFRICA),
799
800  /**
801   * Mayotte.
802   */
803  MAYOTTE("YT", "MYT", 175, "Mayotte", GbifRegion.AFRICA),
804
805  /**
806   * Mexico.
807   */
808  MEXICO("MX", "MEX", 484, "Mexico", GbifRegion.LATIN_AMERICA),
809
810  /**
811   * Micronesia (Federated States of).
812   */
813  MICRONESIA("FM", "FSM", 583, "Micronesia (Federated States of)", GbifRegion.OCEANIA),
814
815  /**
816   * Moldova, Republic of.
817   */
818  MOLDOVA("MD", "MDA", 498, "Moldova, Republic of", GbifRegion.EUROPE),
819
820  /**
821   * Monaco.
822   */
823  MONACO("MC", "MCO", 492, "Monaco", GbifRegion.EUROPE),
824
825  /**
826   * Mongolia.
827   */
828  MONGOLIA("MN", "MNG", 496, "Mongolia", GbifRegion.ASIA),
829
830  /**
831   * Montenegro.
832   */
833  MONTENEGRO("ME", "MNE", 499, "Montenegro", GbifRegion.EUROPE),
834
835  /**
836   * Montserrat.
837   */
838  MONTSERRAT("MS", "MSR", 500, "Montserrat", GbifRegion.LATIN_AMERICA),
839
840  /**
841   * Morocco.
842   */
843  MOROCCO("MA", "MAR", 504, "Morocco", GbifRegion.AFRICA),
844
845  /**
846   * Mozambique.
847   */
848  MOZAMBIQUE("MZ", "MOZ", 508, "Mozambique", GbifRegion.AFRICA),
849
850  /**
851   * Myanmar.
852   */
853  MYANMAR("MM", "MMR", 104, "Myanmar", GbifRegion.ASIA),
854
855  /**
856   * Namibia.
857   */
858  NAMIBIA("NA", "NAM", 516, "Namibia", GbifRegion.AFRICA),
859
860  /**
861   * Nauru.
862   */
863  NAURU("NR", "NRU", 520, "Nauru", GbifRegion.OCEANIA),
864
865  /**
866   * Nepal.
867   */
868  NEPAL("NP", "NPL", 524, "Nepal", GbifRegion.ASIA),
869
870  /**
871   * Netherlands.
872   */
873  NETHERLANDS("NL", "NLD", 528, "Netherlands", GbifRegion.EUROPE),
874
875  /**
876   * New Caledonia.
877   */
878  NEW_CALEDONIA("NC", "NCL", 540, "New Caledonia", GbifRegion.OCEANIA),
879
880  /**
881   * New Zealand.
882   */
883  NEW_ZEALAND("NZ", "NZL", 554, "New Zealand", GbifRegion.OCEANIA),
884
885  /**
886   * Nicaragua.
887   */
888  NICARAGUA("NI", "NIC", 558, "Nicaragua", GbifRegion.LATIN_AMERICA),
889
890  /**
891   * Niger.
892   */
893  NIGER("NE", "NER", 562, "Niger", GbifRegion.AFRICA),
894
895  /**
896   * Nigeria.
897   */
898  NIGERIA("NG", "NGA", 566, "Nigeria", GbifRegion.AFRICA),
899
900  /**
901   * Niue.
902   */
903  NIUE("NU", "NIU", 570, "Niue", GbifRegion.OCEANIA),
904
905  /**
906   * Norfolk Island.
907   */
908  NORFOLK_ISLAND("NF", "NFK", 574, "Norfolk Island", GbifRegion.OCEANIA),
909
910  /**
911   * Northern Mariana Islands.
912   */
913  NORTHERN_MARIANA_ISLANDS("MP", "MNP", 580, "Northern Mariana Islands", GbifRegion.OCEANIA),
914
915  /**
916   * Norway.
917   */
918  NORWAY("NO", "NOR", 578, "Norway", GbifRegion.EUROPE),
919
920  /**
921   * Oman.
922   */
923  OMAN("OM", "OMN", 512, "Oman", GbifRegion.ASIA),
924
925  /**
926   * Pakistan.
927   */
928  PAKISTAN("PK", "PAK", 586, "Pakistan", GbifRegion.ASIA),
929
930  /**
931   * Palau.
932   */
933  PALAU("PW", "PLW", 585, "Palau", GbifRegion.OCEANIA),
934
935  /**
936   * Palestine, State of.
937   */
938  PALESTINIAN_TERRITORY("PS", "PSE", 275, "Palestine, State of", GbifRegion.ASIA),
939
940  /**
941   * Panama.
942   */
943  PANAMA("PA", "PAN", 591, "Panama", GbifRegion.LATIN_AMERICA),
944
945  /**
946   * Papua New Guinea.
947   */
948  PAPUA_NEW_GUINEA("PG", "PNG", 598, "Papua New Guinea", GbifRegion.OCEANIA),
949
950  /**
951   * Paraguay.
952   */
953  PARAGUAY("PY", "PRY", 600, "Paraguay", GbifRegion.LATIN_AMERICA),
954
955  /**
956   * Peru.
957   */
958  PERU("PE", "PER", 604, "Peru", GbifRegion.LATIN_AMERICA),
959
960  /**
961   * Philippines.
962   */
963  PHILIPPINES("PH", "PHL", 608, "Philippines", GbifRegion.ASIA),
964
965  /**
966   * Pitcairn.
967   */
968  PITCAIRN("PN", "PCN", 612, "Pitcairn", GbifRegion.OCEANIA),
969
970  /**
971   * Poland.
972   */
973  POLAND("PL", "POL", 616, "Poland", GbifRegion.EUROPE),
974
975  /**
976   * Portugal.
977   */
978  PORTUGAL("PT", "PRT", 620, "Portugal", GbifRegion.EUROPE),
979
980  /**
981   * Puerto Rico.
982   */
983  PUERTO_RICO("PR", "PRI", 630, "Puerto Rico", GbifRegion.LATIN_AMERICA),
984
985  /**
986   * Qatar.
987   */
988  QATAR("QA", "QAT", 634, "Qatar", GbifRegion.ASIA),
989
990  /**
991   * Réunion.
992   */
993  RÉUNION("RE", "REU", 638, "Réunion", GbifRegion.AFRICA),
994
995  /**
996   * Romania.
997   */
998  ROMANIA("RO", "ROU", 642, "Romania", GbifRegion.EUROPE),
999
1000  /**
1001   * Russian Federation.
1002   */
1003  RUSSIAN_FEDERATION("RU", "RUS", 643, "Russian Federation", GbifRegion.EUROPE),
1004
1005  /**
1006   * Rwanda.
1007   */
1008  RWANDA("RW", "RWA", 646, "Rwanda", GbifRegion.AFRICA),
1009
1010  /**
1011   * Saint Barthélemy.
1012   */
1013  SAINT_BARTHÉLEMY("BL", "BLM", 652, "Saint Barthélemy", GbifRegion.LATIN_AMERICA),
1014
1015  /**
1016   * Saint Helena, Ascension and Tristan da Cunha.
1017   */
1018  SAINT_HELENA_ASCENSION_TRISTAN_DA_CUNHA("SH", "SHN", 654, "Saint Helena, Ascension and Tristan da Cunha", GbifRegion.AFRICA),
1019
1020  /**
1021   * Saint Kitts and Nevis.
1022   */
1023  SAINT_KITTS_NEVIS("KN", "KNA", 659, "Saint Kitts and Nevis", GbifRegion.LATIN_AMERICA),
1024
1025  /**
1026   * Saint Lucia.
1027   */
1028  SAINT_LUCIA("LC", "LCA", 662, "Saint Lucia", GbifRegion.LATIN_AMERICA),
1029
1030  /**
1031   * Saint Martin (French part).
1032   */
1033  SAINT_MARTIN_FRENCH("MF", "MAF", 663, "Saint Martin (French part)", GbifRegion.LATIN_AMERICA),
1034
1035  /**
1036   * Saint Pierre and Miquelon.
1037   */
1038  SAINT_PIERRE_MIQUELON("PM", "SPM", 666, "Saint Pierre and Miquelon", GbifRegion.NORTH_AMERICA),
1039
1040  /**
1041   * Saint Vincent and the Grenadines.
1042   */
1043  SAINT_VINCENT_GRENADINES("VC", "VCT", 670, "Saint Vincent and the Grenadines", GbifRegion.LATIN_AMERICA),
1044
1045  /**
1046   * Samoa.
1047   */
1048  SAMOA("WS", "WSM", 882, "Samoa", GbifRegion.OCEANIA),
1049
1050  /**
1051   * San Marino.
1052   */
1053  SAN_MARINO("SM", "SMR", 674, "San Marino", GbifRegion.EUROPE),
1054
1055  /**
1056   * Sao Tome and Principe.
1057   */
1058  SAO_TOME_PRINCIPE("ST", "STP", 678, "Sao Tome and Principe", GbifRegion.AFRICA),
1059
1060  /**
1061   * Saudi Arabia.
1062   */
1063  SAUDI_ARABIA("SA", "SAU", 682, "Saudi Arabia", GbifRegion.ASIA),
1064
1065  /**
1066   * Senegal.
1067   */
1068  SENEGAL("SN", "SEN", 686, "Senegal", GbifRegion.AFRICA),
1069
1070  /**
1071   * Serbia.
1072   */
1073  SERBIA("RS", "SRB", 688, "Serbia", GbifRegion.EUROPE),
1074
1075  /**
1076   * Seychelles.
1077   */
1078  SEYCHELLES("SC", "SYC", 690, "Seychelles", GbifRegion.AFRICA),
1079
1080  /**
1081   * Sierra Leone.
1082   */
1083  SIERRA_LEONE("SL", "SLE", 694, "Sierra Leone", GbifRegion.AFRICA),
1084
1085  /**
1086   * Singapore.
1087   */
1088  SINGAPORE("SG", "SGP", 702, "Singapore", GbifRegion.ASIA),
1089
1090  /**
1091   * Sint Maarten (Dutch part).
1092   */
1093  SINT_MAARTEN("SX", "SXM", 534, "Sint Maarten (Dutch part)", GbifRegion.LATIN_AMERICA),
1094
1095  /**
1096   * Slovakia.
1097   */
1098  SLOVAKIA("SK", "SVK", 703, "Slovakia", GbifRegion.EUROPE),
1099
1100  /**
1101   * Slovenia.
1102   */
1103  SLOVENIA("SI", "SVN", 705, "Slovenia", GbifRegion.EUROPE),
1104
1105  /**
1106   * Solomon Islands.
1107   */
1108  SOLOMON_ISLANDS("SB", "SLB", 90, "Solomon Islands", GbifRegion.OCEANIA),
1109
1110  /**
1111   * Somalia.
1112   */
1113  SOMALIA("SO", "SOM", 706, "Somalia", GbifRegion.AFRICA),
1114
1115  /**
1116   * South Africa.
1117   */
1118  SOUTH_AFRICA("ZA", "ZAF", 710, "South Africa", GbifRegion.AFRICA),
1119
1120  /**
1121   * South Georgia and the South Sandwich Islands.
1122   */
1123  SOUTH_GEORGIA_SANDWICH_ISLANDS("GS", "SGS", 239, "South Georgia and the South Sandwich Islands", GbifRegion.ANTARCTICA),
1124
1125  /**
1126   * South Sudan.
1127   */
1128  SOUTH_SUDAN("SS", "SSD", 728, "South Sudan", GbifRegion.AFRICA),
1129
1130  /**
1131   * Spain.
1132   */
1133  SPAIN("ES", "ESP", 724, "Spain", GbifRegion.EUROPE),
1134
1135  /**
1136   * Sri Lanka.
1137   */
1138  SRI_LANKA("LK", "LKA", 144, "Sri Lanka", GbifRegion.ASIA),
1139
1140  /**
1141   * Sudan.
1142   */
1143  SUDAN("SD", "SDN", 729, "Sudan", GbifRegion.AFRICA),
1144
1145  /**
1146   * Suriname.
1147   */
1148  SURINAME("SR", "SUR", 740, "Suriname", GbifRegion.LATIN_AMERICA),
1149
1150  /**
1151   * Svalbard and Jan Mayen.
1152   */
1153  SVALBARD_JAN_MAYEN("SJ", "SJM", 744, "Svalbard and Jan Mayen", GbifRegion.EUROPE),
1154
1155  /**
1156   * Swaziland.
1157   */
1158  SWAZILAND("SZ", "SWZ", 748, "Eswatini", GbifRegion.AFRICA),
1159
1160  /**
1161   * Sweden.
1162   */
1163  SWEDEN("SE", "SWE", 752, "Sweden", GbifRegion.EUROPE),
1164
1165  /**
1166   * Switzerland.
1167   */
1168  SWITZERLAND("CH", "CHE", 756, "Switzerland", GbifRegion.EUROPE),
1169
1170  /**
1171   * Syrian Arab Republic.
1172   */
1173  SYRIA("SY", "SYR", 760, "Syrian Arab Republic", GbifRegion.ASIA),
1174
1175  /**
1176   * Taiwan, Province of China.
1177   */
1178  /*
1179   * Decision by EC, September 2020: The name is to be "Chinese Taipei".
1180   */
1181  TAIWAN("TW", "TWN", 158, "Chinese Taipei", GbifRegion.ASIA),
1182
1183  /**
1184   * Tajikistan.
1185   */
1186  TAJIKISTAN("TJ", "TJK", 762, "Tajikistan", GbifRegion.EUROPE),
1187
1188  /**
1189   * Tanzania, United Republic of.
1190   */
1191  TANZANIA("TZ", "TZA", 834, "Tanzania, United Republic of", GbifRegion.AFRICA),
1192
1193  /**
1194   * Thailand.
1195   */
1196  THAILAND("TH", "THA", 764, "Thailand", GbifRegion.ASIA),
1197
1198  /**
1199   * Timor-Leste.
1200   */
1201  TIMOR_LESTE("TL", "TLS", 626, "Timor-Leste", GbifRegion.ASIA),
1202
1203  /**
1204   * Togo.
1205   */
1206  TOGO("TG", "TGO", 768, "Togo", GbifRegion.AFRICA),
1207
1208  /**
1209   * Tokelau.
1210   */
1211  TOKELAU("TK", "TKL", 772, "Tokelau", GbifRegion.OCEANIA),
1212
1213  /**
1214   * Tonga.
1215   */
1216  TONGA("TO", "TON", 776, "Tonga", GbifRegion.OCEANIA),
1217
1218  /**
1219   * Trinidad and Tobago.
1220   */
1221  TRINIDAD_TOBAGO("TT", "TTO", 780, "Trinidad and Tobago", GbifRegion.LATIN_AMERICA),
1222
1223  /**
1224   * Tunisia.
1225   */
1226  TUNISIA("TN", "TUN", 788, "Tunisia", GbifRegion.AFRICA),
1227
1228  /**
1229   * Türkiye.
1230   */
1231  TURKEY("TR", "TUR", 792, "Türkiye", GbifRegion.EUROPE),
1232
1233  /**
1234   * Turkmenistan.
1235   */
1236  TURKMENISTAN("TM", "TKM", 795, "Turkmenistan", GbifRegion.EUROPE),
1237
1238  /**
1239   * Turks and Caicos Islands.
1240   */
1241  TURKS_CAICOS_ISLANDS("TC", "TCA", 796, "Turks and Caicos Islands", GbifRegion.LATIN_AMERICA),
1242
1243  /**
1244   * Tuvalu.
1245   */
1246  TUVALU("TV", "TUV", 798, "Tuvalu", GbifRegion.OCEANIA),
1247
1248  /**
1249   * Uganda.
1250   */
1251  UGANDA("UG", "UGA", 800, "Uganda", GbifRegion.AFRICA),
1252
1253  /**
1254   * Ukraine.
1255   */
1256  UKRAINE("UA", "UKR", 804, "Ukraine", GbifRegion.EUROPE),
1257
1258  /**
1259   * United Arab Emirates.
1260   */
1261  UNITED_ARAB_EMIRATES("AE", "ARE", 784, "United Arab Emirates", GbifRegion.ASIA),
1262
1263  /**
1264   * United Kingdom of Great Britain and Northern Ireland.
1265   */
1266  UNITED_KINGDOM("GB", "GBR", 826, "United Kingdom of Great Britain and Northern Ireland", GbifRegion.EUROPE),
1267
1268  /**
1269   * United States of America.
1270   */
1271  UNITED_STATES("US", "USA", 840, "United States of America", GbifRegion.NORTH_AMERICA),
1272
1273  /**
1274   * United States Minor Outlying Islands.
1275   */
1276  UNITED_STATES_OUTLYING_ISLANDS("UM", "UMI", 581, "United States Minor Outlying Islands", GbifRegion.OCEANIA),
1277
1278  /**
1279   * Uruguay.
1280   */
1281  URUGUAY("UY", "URY", 858, "Uruguay", GbifRegion.LATIN_AMERICA),
1282
1283  /**
1284   * Uzbekistan.
1285   */
1286  UZBEKISTAN("UZ", "UZB", 860, "Uzbekistan", GbifRegion.EUROPE),
1287
1288  /**
1289   * Vanuatu.
1290   */
1291  VANUATU("VU", "VUT", 548, "Vanuatu", GbifRegion.OCEANIA),
1292
1293  /**
1294   * Venezuela (Bolivarian Republic of).
1295   */
1296  VENEZUELA("VE", "VEN", 862, "Venezuela (Bolivarian Republic of)", GbifRegion.LATIN_AMERICA),
1297
1298  /**
1299   * Viet Nam.
1300   */
1301  VIETNAM("VN", "VNM", 704, "Viet Nam", GbifRegion.ASIA),
1302
1303  /**
1304   * Virgin Islands (British).
1305   */
1306  VIRGIN_ISLANDS_BRITISH("VG", "VGB", 92, "Virgin Islands (British)", GbifRegion.LATIN_AMERICA),
1307
1308  /**
1309   * Virgin Islands, (U.S.).
1310   */
1311  VIRGIN_ISLANDS("VI", "VIR", 850, "Virgin Islands (U.S.)", GbifRegion.LATIN_AMERICA),
1312
1313  /**
1314   * Wallis and Futuna.
1315   */
1316  WALLIS_FUTUNA("WF", "WLF", 876, "Wallis and Futuna", GbifRegion.OCEANIA),
1317
1318  /**
1319   * Western Sahara.
1320   */
1321  WESTERN_SAHARA("EH", "ESH", 732, "Western Sahara", GbifRegion.AFRICA),
1322
1323  /**
1324   * Yemen.
1325   */
1326  YEMEN("YE", "YEM", 887, "Yemen", GbifRegion.ASIA),
1327
1328  /**
1329   * Zambia.
1330   */
1331  ZAMBIA("ZM", "ZMB", 894, "Zambia", GbifRegion.AFRICA),
1332
1333  /**
1334   * Zimbabwe.
1335   */
1336  ZIMBABWE("ZW", "ZWE", 716, "Zimbabwe", GbifRegion.AFRICA),
1337
1338  /**
1339   * Bucket for all user defined codes not managed by GBIF.
1340   *
1341   * User-assigned code elements are codes at the disposal of users who need to add further names
1342   * of countries, territories, or other geographical entities to their in-house application of ISO 3166-1,
1343   * and the ISO 3166/MA will never use these codes in the updating process of the standard.
1344   *
1345   * The following codes can be user-assigned:
1346   * Alpha-2: AA, QM to QZ, XA to XZ, and ZZ
1347   * Alpha-3: AAA to AAZ, QMA to QZZ, XAA to XZZ, and ZZA to ZZZ
1348   * Numeric: 900 to 999
1349   */
1350  USER_DEFINED("AA", "AAA", 900, "user defined"),
1351
1352  /**
1353   * Kosovo.
1354   * User-assigned temporary code, XK and XKX are the same as used by several other international organizations.
1355   * 902 is assigned by GBIF, but these codes aren't used anywhere.
1356   */
1357  KOSOVO("XK", "XKX", 902, "Kosovo", GbifRegion.EUROPE),
1358
1359  /**
1360   * Taken from {@link <a href="https://en.wikipedia.org/wiki/UN/LOCODE">UN/LOCODE</a>}
1361   */
1362  INTERNATIONAL_WATERS("XZ", "XZZ", 901, "international waters"),
1363
1364  /**
1365   * Unknown or Invalid territory.
1366   *
1367   * <p>See {@link <a href="https://en.wikipedia.org/wiki/Common_Locale_Data_Repository">Unicode Common Locale Data Repository</a>}
1368   */
1369  UNKNOWN("ZZ", "ZZZ", 999, "unknown or invalid");
1370
1371  /**
1372   * A set of all 2- and 3-letter codes that are reserved by ISO for custom application specific usages.
1373   * The following codes can be user-assigned:
1374   * Alpha-2: AA, QM to QZ, XA to XZ, and ZZ
1375   * Alpha-3: AAA to AAZ, QMA to QZZ, XAA to XZZ, and ZZA to ZZZ
1376   */
1377  public static final Set<String> CUSTOM_CODES;
1378  public static final List<Country> OFFICIAL_COUNTRIES;
1379
1380  private final String alpha2;
1381  private final String alpha3;
1382  private final int numericalCode;
1383  private final String title;
1384  private final GbifRegion gbifRegion;
1385
1386  static {
1387    List<Country> officials = new ArrayList<>();
1388    for (Country c : Country.values()) {
1389      if (c.isOfficial()) {
1390        officials.add(c);
1391      }
1392    }
1393    OFFICIAL_COUNTRIES = Collections.unmodifiableList(officials);
1394
1395    Set<String> custom = new HashSet<>();
1396    custom.add("AA");
1397    custom.add("ZZ");
1398
1399    // QM-QZ
1400    for (char c = 'M'; c <= 'Z'; c++) {
1401      custom.add("Q" + c);
1402    }
1403    // AAA-AAZ, ZZA-ZZZ
1404    for (char c = 'A'; c <= 'Z'; c++) {
1405      custom.add("AA" + c);
1406      custom.add("ZZ" + c);
1407    }
1408    // QMA-QZZ
1409    for (char c = 'M'; c <= 'Z'; c++) {
1410      for (char c2 = 'A'; c2 <= 'Z'; c2++) {
1411        custom.add("Q" + c + c2);
1412      }
1413    }
1414    // XA-XZ, XAA to XZZ
1415    for (char c = 'A'; c <= 'Z'; c++) {
1416      custom.add("X" + c);
1417      for (char c2 = 'A'; c2 <= 'Z'; c2++) {
1418        custom.add("X" + c + c2);
1419      }
1420    }
1421
1422    CUSTOM_CODES = Collections.unmodifiableSet(custom);
1423  }
1424
1425  public static boolean isCustomCode(String code) {
1426    return code != null && CUSTOM_CODES.contains(code.toUpperCase());
1427  }
1428
1429  /**
1430   * @param code the case-insensitive 2- or 3-letter codes
1431   * @return the matching country or null
1432   */
1433  public static Country fromIsoCode(String code) {
1434    if (StringUtils.isNotEmpty(code)) {
1435      String codeUpper = code.toUpperCase().trim();
1436      for (Country c : Country.values()) {
1437        if (codeUpper.equals(c.getIso2LetterCode()) || codeUpper.equals(c.getIso3LetterCode())) {
1438          return c;
1439        }
1440      }
1441    }
1442    return null;
1443  }
1444
1445  /**
1446   * Constructor for custom codes without a GBIF Region.
1447   *
1448   * @param alpha2
1449   * @param alpha3
1450   * @param numericalCode
1451   * @param title
1452   */
1453  Country(String alpha2, String alpha3, int numericalCode, String title) {
1454    this(alpha2, alpha3, numericalCode, title, null);
1455  }
1456
1457  /**
1458   * @param alpha2
1459   * @param alpha3
1460   * @param numericalCode
1461   * @param title
1462   * @param gbifRegion    GBIF region is NOT a geographic region. Participant countries make an active decision which
1463   *                      GBIF region they want to belong to.
1464   */
1465  Country(String alpha2, String alpha3, int numericalCode, String title, GbifRegion gbifRegion) {
1466    this.alpha2 = alpha2;
1467    this.alpha3 = alpha3;
1468    this.numericalCode = numericalCode;
1469    this.title = title;
1470    this.gbifRegion = gbifRegion;
1471  }
1472
1473  /**
1474   * @return the country name in the English language as maintained by ISO.
1475   */
1476  public String getTitle() {
1477    return title;
1478  }
1479
1480  /**
1481   * @return the 2-letter ISO 3166-1 ALPHA2 code in upper case.
1482   */
1483  @JsonValue
1484  public String getIso2LetterCode() {
1485    return alpha2;
1486  }
1487
1488  /**
1489   * @return the 3-letter ISO 3166-1 ALPHA3 code in upper case.
1490   */
1491  public String getIso3LetterCode() {
1492    return alpha3;
1493  }
1494
1495  /**
1496   * @return the numerical ISO 3166-1 code.
1497   */
1498  public Integer getIsoNumericalCode() {
1499    return numericalCode;
1500  }
1501
1502  /**
1503   * @return the {@link GbifRegion} associated with this {@link Country}.
1504   */
1505  public GbifRegion getGbifRegion() {
1506    return gbifRegion;
1507  }
1508
1509  /**
1510   * Note this includes Kosovo (XK).
1511   * <br>
1512   * @return true if it's an ISO 3166-1 alpha2 code officially used by GBIF.
1513   */
1514  public boolean isOfficial() {
1515    return !(this == UNKNOWN || this == USER_DEFINED || this == INTERNATIONAL_WATERS);
1516  }
1517
1518  /**
1519   * Serializes the value as the English country title.
1520   */
1521  public static class TitleSerializer extends JsonSerializer<Country> {
1522    @Override
1523    public void serialize(Country value, JsonGenerator jgen, SerializerProvider provider) throws IOException {
1524      jgen.writeString(value.title);
1525    }
1526  }
1527
1528  /**
1529   * Deserializes the value from an English country title exactly as given by the enumeration.
1530   */
1531  public static class TitleDeserializer extends JsonDeserializer<Country> {
1532
1533    private static Map<String, Country> TITLE_LOOKUP =
1534      Stream.of(Country.values())
1535        .collect(
1536          Collectors.toMap(
1537            country -> country.title,
1538            country -> country,
1539            (e1, e2) -> e1,
1540            LinkedHashMap::new));
1541
1542    @Override
1543    public Country deserialize(JsonParser jp, DeserializationContext ctxt) throws IOException {
1544      try {
1545        return TITLE_LOOKUP.get(jp.getText());
1546      } catch (Exception e) {
1547        throw new IOException("Unable to deserialize country from provided title : " + jp.getText());
1548      }
1549    }
1550  }
1551
1552  /**
1553   * Serializes the value in a 2-letter ISO format.
1554   */
1555  public static class IsoSerializer extends JsonSerializer<Country> {
1556    @Override
1557    public void serialize(Country value, com.fasterxml.jackson.core.JsonGenerator jgen, com.fasterxml.jackson.databind.SerializerProvider provider) throws IOException {
1558      jgen.writeString(value.getIso2LetterCode());
1559    }
1560  }
1561
1562  /**
1563   * Deserializes the value from a 2-letter ISO format.
1564   */
1565  public static class IsoDeserializer extends StdDeserializer<Country> {
1566
1567    public IsoDeserializer() {
1568      super(Country.class);
1569    }
1570
1571    @Override
1572    public Country deserialize(com.fasterxml.jackson.core.JsonParser jp, com.fasterxml.jackson.databind.DeserializationContext ctxt) throws IOException {
1573      try {
1574        if (jp != null && jp.getTextLength() > 0) {
1575          return Country.fromIsoCode(jp.getText());
1576        } else {
1577          return Country.UNKNOWN; // none provided
1578        }
1579      } catch (Exception e) {
1580        throw new IOException("Unable to deserialize country from provided value (not an ISO 2 character?): "
1581          + jp.getText());
1582      }
1583    }
1584  }
1585}