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