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