DEV Community: psstepniewski

Difference between `yyyy` and `YYYY` Java date pattern. What is week-based-year?

psstepniewski — Sun, 09 Jan 2022 10:30:01 +0000

No matter what application you are working on, it probably somewhere formats dates as String. If you not sure what is the difference between yyyy and YYYY patterns you might have been surprised in the last week of 2021. Or you even not noticed that something is wrong, because from 2022 everything works fine again. Possible consequence - in my case a component starts rejecting notifications from external service.

The reason was wrong value of calculated sign hash. When I check signed String it turned out that date was formatted as 2022-12-28 instead of 2021-12-28. Question was: why I got 2022 year if there still was 2021? The component worked as follows: received date field was automatically parsed to Date object type, later it was formatted as String with DateTimeFormatter using YYYY-MM-dd pattern. To fix problem I just used yyyy-MM-dd pattern instead. Difference between YYYY and yyyy according to DateTimeFormatter documentation:

YYYY is "week-based-year"
yyyy is "year-of-era"

What means "week-based-year"? According to WeekFields Java documentation

A week is defined by:

The first day-of-week. For example, the ISO-8601 standard considers Monday to be the first day-of-week.

The minimal number of days in the first week. For example, the ISO-8601 standard counts the first week as needing at least 4 days.

The ISO-8601 definition, where a week starts on Monday and the first week has a minimum of 4 days.

For my Locale(pl-PL) Java uses ISO-8601 definitions:

There are several mutually equivalent and compatible descriptions of week 01:

the week with the starting year's first Thursday in it (the formal ISO definition),

the week with 4 January in it,

the first week with the majority (four or more) of its days in the starting year, and

the week starting with the Monday in the period 29 December - 4 January.

According to this definition the first week of 2022 is week from 3rd January to 9th January.

All the following assertions are true.



@Test
@DisplayName("Locale.PL uses WeekFields.ISO")
public void localePlUsesWeekFieldsIso() {
    DateTimeFormatter formatterPl = DateTimeFormatter.ofPattern("YYYY-MM-dd ww", Locale.forLanguageTag("pl-PL"));
    assertEquals(LocalDate.of(2021, 12, 25).format(formatterPl), "2021-12-25 51");
    assertEquals(LocalDate.of(2021, 12, 26).format(formatterPl), "2021-12-26 51");
    assertEquals(LocalDate.of(2021, 12, 27).format(formatterPl), "2021-12-27 52");
    assertEquals(LocalDate.of(2021, 12, 28).format(formatterPl), "2021-12-28 52");
    assertEquals(LocalDate.of(2021, 12, 29).format(formatterPl), "2021-12-29 52");
    assertEquals(LocalDate.of(2021, 12, 30).format(formatterPl), "2021-12-30 52");
    assertEquals(LocalDate.of(2021, 12, 31).format(formatterPl), "2021-12-31 52");
    assertEquals(LocalDate.of(2022, 1, 1).format(formatterPl), "2021-01-01 52");
    assertEquals(LocalDate.of(2022, 1, 2).format(formatterPl), "2021-01-02 52");
    assertEquals(LocalDate.of(2022, 1, 3).format(formatterPl), "2022-01-03 01");
}

Pattern YYYY-MM-dd ww prints week-based-year (YYYY), month-of-year (MM), day-of-month (dd) and week-of-week-based-year(ww). Pay attention that formatter with YYYY pattern prints 2021 year for the two first days of 2022: LocalDate.of(2022, 1, 1) and LocalDate.of(2022, 1, 2) because, according to ISO-8601 definition, these days belong to the last week of 2021 (52nd week of 2021). If you want get day-based-year (or year-of-era) use yyyy pattern instead of YYYY.

But if the above definition would be always true the component should reject notifications in the first days of 2022 not the last days of 2021. The catch is that ISO definition of week is not used for all Locales. For example if you use Locale.US and run above example, you will be surprised again. Because for Locale.US Java uses Sunday start definition of week. According to WeekFields Java documentation

The common definition of a week that starts on Sunday and the first week has a minimum of 1 day.

According to the above definition the first week is week from 26th December to 1st January. All the following assertions are true.



@Test
@DisplayName("Locale.US uses WeekFields.SUNDAY_START")
public void localeUsUsesWeekFieldsSundayStart() {
    DateTimeFormatter formatterUs = DateTimeFormatter.ofPattern("YYYY-MM-dd ww", Locale.US);
    assertEquals(LocalDate.of(2021, 12, 25).format(formatterUs), "2021-12-25 52");
    assertEquals(LocalDate.of(2021, 12, 26).format(formatterUs), "2022-12-26 01");
    assertEquals(LocalDate.of(2021, 12, 27).format(formatterUs), "2022-12-27 01");
    assertEquals(LocalDate.of(2021, 12, 28).format(formatterUs), "2022-12-28 01");
    assertEquals(LocalDate.of(2021, 12, 29).format(formatterUs), "2022-12-29 01");
    assertEquals(LocalDate.of(2021, 12, 30).format(formatterUs), "2022-12-30 01");
    assertEquals(LocalDate.of(2021, 12, 31).format(formatterUs), "2022-12-31 01");
    assertEquals(LocalDate.of(2022, 1, 1).format(formatterUs), "2022-01-01 01");
    assertEquals(LocalDate.of(2022, 1, 2).format(formatterUs), "2022-01-02 02");
    assertEquals(LocalDate.of(2022, 1, 3).format(formatterUs), "2022-01-03 02");
}

Formatter with YYYY pattern prints 2022 starting on 26th December because, according to Sunday start definition, these days belong to the first week of 2022.

In general, week in Java is defined by WeekFields class which encapsulates two mentioned earlier "week-defining" values:

The first day-of-week.

The minimal number of days in the first week.

If you are interesting which WeekFields is used for your Locale, you can check it easily. The following code prints all possible WeekField definition with all assigned to it Locales.



public class PrintLocaleWeekFields {

    public static void main(String[] args) {
        Map<WeekFields, List<Locale>> locales = Arrays.stream(Locale.getAvailableLocales())
            .collect(Collectors.groupingBy(WeekFields::of));
        System.out.println(locales);
    }
}

Printed result:



WeekFields[MONDAY,1]=[tk_TM_#Latn, en_NU, ff_LR_#Adlm, es_BO, bs_BA, en_LR, ar_TD, nus_SS_#Latn, ff_MR_#Latn, sw_UG, tk_TM, sr_ME_#Cyrl, os_GE_#Cyrl, yo_NG, en_PW, sr_CS, agq_CM_#Latn, ar_EH, bs_BA_#Latn, dje_NE, hy_AM_#Armn, ff_GH_#Latn, fr_PM, ar_KM, agq_CM, tr_TR, kl_GL_#Latn, ar_MR, kl_GL, en_NR, rw_RW_#Latn, en_CY, tr_TR_#Latn, ti_ER, nus_SS, en_RW, hr_HR_#Latn, ln_CD, nnh_CM, dje_NE_#Latn, ksf_CM, fr_VU, nnh_CM_#Latn, fr_NE, bez_TZ_#Latn, ksb_TZ, ln_CF, en_CX, ak_GH_#Latn, en_TZ, fr_NC, fr_CM, pcm_NG_#Latn, teo_UG, ln_CG, az_AZ, el_CY, ku_TR, ff_SN, sq_MK, sr_BA_#Cyrl, so_SO_#Latn, tr_CY, lv_LV_#Latn, uz_UZ_#Latn, dua_CM, fr_TN, sr_RS, sw_TZ_#Latn, fr_PF, pt_GQ, vun_TZ, jmc_TZ, mg_MG_#Latn, en_TV, en_PN, lu_CD_#Latn, en_GY, dyo_SN, nl_CW, fr_GQ, en_NG, fr_CI, ia_001, en_LC, ff_BF_#Adlm, bm_ML_#Latn, yav_CM_#Latn, mk_MK, sl_SI, sg_CF_#Latn, jgo_CM, ff_NE_#Adlm, en_BM, kea_CV, vi_VN, mfe_MU, fr_BF, fr_YT, ff_CM_#Latn, sr_BA_#Latn, uk_UA_#Cyrl, ff_GW_#Adlm, ha_GH, yi_001_#Hebr, to_TO_#Latn, ff_GW_#Latn, mua_CM_#Latn, nyn_UG, ms_MY, rn_BI_#Latn, ta_LK, tg_TJ, vun_TZ_#Latn, es_EC, mk_MK_#Cyrl, ff_CM_#Adlm, lg_UG, ff_NE_#Latn, cgg_UG, pcm_NG, en_BI, mi_NZ, ar_ER, es_EA, fr_SC, en_SL, ff_NG_#Latn, ff_NG_#Adlm, en_SH, eo_001, en_SI, vai_LR_#Vaii, rof_TZ_#Latn, ar_LB, ff_GN, eo_001_#Latn, hr_HR, rof_TZ, mn_MN, en_FM, fr_WF, ff_GM_#Latn, teo_UG_#Latn, asa_TZ_#Latn, bez_TZ, ff_GN_#Latn, sl_SI_#Latn, en_FK, bas_CM_#Latn, en_DG, pt_ST, ak_GH, es_419, ln_CD_#Latn, kkj_CM_#Latn, es_IC, ar_TN, bm_ML, jmc_TZ_#Latn, khq_ML, en_SB, rw_RW, shi_MA_#Tfng, ro_MD, uz_UZ, ia_001_#Latn, en_SC, en_UG, en_NZ, es_UY, ru_UA, sg_CF, en_BB, hr_BA, yo_NG_#Latn, lu_CD, ar_001, so_SO, lv_LV, sr_RS_#Cyrl, en_LS, ka_GE, sw_TZ, fr_RW, mg_MG, sr_RS_#Latn, ky_KG, tzm_MA_#Latn, ku_TR_#Latn, mfe_MU_#Latn, ky_KG_#Cyrl, qu_EC, ka_GE_#Geor, en_MS, kde_TZ_#Latn, sr_ME, en_ZM, fr_ML, ha_NG, os_GE, yi_001, en_GH, tzm_MA, ses_ML, rwk_TZ_#Latn, vai_LR_#Latn, sw_CD, ff_MR_#Adlm, en_VC, ses_ML_#Latn, en_150, ha_NE, en_KN, ro_RO, sr_ME_#Latn, ff_LR_#Latn, bas_CM, fr_MG, es_CL, sq_AL, ro_RO_#Latn, twq_NE, nmg_CM, en_MP, en_GD, sbp_TZ_#Latn, kde_TZ, ta_MY, si_LK_#Sinh, en_KI, twq_NE_#Latn, sq_AL_#Latn, ff_GH_#Adlm, fr_MF, en_SZ, rwk_TZ, kk_KZ, ar_PS, kkj_CM, es_GQ, en_SX, ru_KZ, ko_KP, nl_SR, bem_ZM_#Latn, cgg_UG_#Latn, nl_BQ, ee_GH_#Latn, ff_GN_#Adlm, uz_UZ_#Cyrl, asa_TZ, fr_SN, fr_MA, ff_GM_#Adlm, fr_BL, mgo_CM, nmg_CM_#Latn, tg_TJ_#Cyrl, en_SS, shi_MA, en_MG, fr_BI, naq_NA_#Latn, fr_BJ, vai_LR, bs_BA_#Cyrl, khq_ML_#Latn, mn_MN_#Cyrl, wo_SN, ha_NG_#Latn, fr_HT, nl_SX, fr_CG, ms_MY_#Latn, zgh_MA_#Tfng, nyn_UG_#Latn, en_VU, to_TO, ff_SL_#Latn, xog_UG_#Latn, ff_SN_#Adlm, vi_VN_#Latn, jgo_CM_#Latn, zgh_MA, uk_UA, lg_UG_#Latn, en_NF, sr_XK_#Cyrl, ar_SS, nl_AW, en_AI, xog_UG, en_CM, ru_MD, ff_SN_#Latn, en_TO, ff_SL_#Adlm, en_PG, fr_CF, pt_TL, en_ER, sr_BA, be_BY_#Cyrl, fr_TG, sr_XK_#Latn, ig_NG, fr_GN, en_CK, ar_MA, fr_TD, bem_ZM, ewo_CM_#Latn, ewo_CM, fr_CD, rn_BI, en_NA, mgo_CM_#Latn, lag_TZ, qu_BO, kea_CV_#Latn, sq_XK, mi_NZ_#Latn, en_KY, si_LK, ar_SO, fr_MU, en_TK, mua_CM, pt_GW, ee_TG, ln_AO, be_BY, pt_CV, ru_BY, ee_GH, kk_KZ_#Cyrl, yo_BJ, fr_KM, es_AR, en_MY, sbp_TZ, hy_AM, en_GM, ksb_TZ_#Latn, pt_AO, en_001, dua_CM_#Latn, lag_TZ_#Latn, ru_KG, fr_MR, ksf_CM_#Latn, ff_BF_#Latn, en_MW, naq_NA, en_IO, en_CC, az_AZ_#Cyrl, shi_MA_#Latn, es_CU, ig_NG_#Latn, yav_CM, da_GL, wo_SN_#Latn, es_CR, fr_GA, en_MU, az_AZ_#Latn, dyo_SN_#Latn, en_VG, en_TC, af_NA, mas_TZ, ms_BN],
WeekFields[SATURDAY,1]=[ar_EG, ps_AF_#Arab, ar_SY, uz_AF, lrc_IR, ar_OM, lrc_IQ, ar_DZ, fa_IR_#Arab, fr_DJ, so_DJ, lrc_IR_#Arab, ar_AE, mzn_IR, en_SD, uz_AF_#Arab, ar_IQ, ar_KW, ar_JO, fr_DZ, fa_AF, ckb_IQ_#Arab, ar_SD, fa_IR, kab_DZ_#Latn, kab_DZ, ps_AF, mzn_IR_#Arab, en_AE, ar_BH, ar_QA, ar_EG_#Arab, ckb_IQ, ckb_IR, ar_LY, fr_SY, ar_DJ],
WeekFields[MONDAY,4]=[se_NO_#Latn, dsb_DE, lb_LU_#Latn, se_NO, pl_PL, nds_DE, nb_SJ, lb_LU, dsb_DE_#Latn, is_IS_#Latn, no_NO_NY, pl_PL_#Latn, nds_DE_#Latn, tt_RU, fur_IT_#Latn, ast_ES_#Latn, en_JE, da_DK_#Latn, en_AT, gd_GB, wae_CH_#Latn, no_NO_#Latn, smn_FI_#Latn, en_NL, gsw_FR, hu_HU, bg_BG_#Cyrl, et_EE, fy_NL, de_IT, de_CH, nl_NL, pt_CH, gv_IM, kw_GB_#Latn, fi_FI_#Latn, fr_BE, nb_NO, it_SM, fi_FI, ca_FR, de_BE, de_DE_#Latn, fr_FR_#Latn, ksh_DE, ru_RU, ga_IE, rm_CH_#Latn, fr_LU, ga_GB, no_NO, de_LU, de_DE, nn_NO_#Latn, en_DK, lt_LT, ksh_DE_#Latn, da_DK, en_BE, tt_RU_#Cyrl, ga_IE_#Latn, is_IS, en_SE, gsw_LI, kw_GB, en_DE, en_FI, sah_RU_#Cyrl, en_FJ, de_LI, smn_FI, de_AT, ce_RU, os_RU, nl_NL_#Latn, gl_ES_#Latn, en_GG, sv_SE, el_GR_#Grek, it_VA, es_ES, bg_BG, hsb_DE, eu_ES_#Latn, sv_SE_#Latn, sv_FI, en_IE, fo_FO_#Latn, en_GB, fr_MC, ce_RU_#Cyrl, gsw_CH, pt_LU, hsb_DE_#Latn, br_FR_#Latn, es_ES_#Latn, cy_GB_#Latn, fr_FR, sah_RU, sk_SK, ru_RU_#Cyrl, gv_IM_#Latn, nds_NL, fr_RE, fr_GP, fr_CH, nb_NO_#Latn, fy_NL_#Latn, cs_CZ, ca_ES, hu_HU_#Latn, rm_CH, et_EE_#Latn, gd_GB_#Latn, se_FI, lt_LT_#Latn, ca_IT, ca_AD, it_CH, it_IT, nn_NO, se_SE, it_IT_#Latn, wae_CH, fo_DK, en_CH, fo_FO, ast_ES, fr_MQ, fur_IT, fr_GF, sk_SK_#Latn, eu_ES, el_GR, ca_ES_VALENCIA, gl_ES, en_IM, gsw_CH_#Latn, en_GI, ca_ES_#Latn, nl_BE, cy_GB, sv_AX, cs_CZ_#Latn, br_FR],
WeekFields[SUNDAY,1]=[, he, th_TH_#Thai, nds, ti_ET, ta_SG, lv, zh_SG_#Hans, en_JM, kkj, sd__#Arab, dz_BT, mni, yi, cs, el, af, smn, dsb, khq, ne_IN, es_US, sa, en_US_POSIX, pt_MO, zh__#Hans, so_KE, gu_IN_#Gujr, teo, eu, es_DO, ru, az, su__#Latn, fa, nd, kk, hy, en_AU, ksb, luo, lb, su, no, ar_IL, mgh, or_IN, az__#Latn, ta, lag, luo_KE_#Latn, bo, om_KE, en_AS, zh_TW, sd_IN, kln, mai, pt_MZ, my_MM_#Mymr, gl, sr__#Cyrl, yue_CN_#Hans, ff__#Adlm, kn_IN, ga, qu, en_PR, mua, jv, ps, sn, km, zgh, es, jgo, gsw, pa_IN_#Guru, ur_PK_#Arab, ceb, bn_BD_#Beng, ne_NP_#Deva, te, sl, mr_IN, ha, guz_KE_#Latn, es_HN, sbp, sw, nmg, pt_BR_#Latn, vai__#Vaii, gu, lo, zh_HK_#Hans, bs__#Latn, os, am, ki_KE, en_PK, zh_CN, rw, brx_IN, en_TT, dav, ses, xh_ZA, es_VE, mer_KE, mg, mr, seh, mgo, en_US, pa__#Guru, sa_IN_#Deva, gu_IN, ast, mt_MT_#Latn, yue__#Hans, ccp_BD_#Cakm, ks__#Arab, af_ZA_#Latn, ti_ET_#Ethi, am_ET_#Ethi, cgg, zh_MO, ksf, cy, ceb_PH, sq, fr, qu_PE, de, zu_ZA, su_ID_#Latn, lg, en_DM, sd, he_IL_#Hebr, yue_CN, en_WS, so, kab, nus, sn_ZW, th_TH_TH_#u-nu-thai, hi, zh_MO_#Hant, vai, sd_PK_#Arab, mi, mt, yav, kam, ro, ps_PK, ee, en_UM, lo_LA, chr, af_ZA, doi, es_BZ, as, it, ks_IN, my_MM, ur_PK, ii, naq, en_SG, kln_KE, tzm, fur, om, mai_IN_#Deva, ja_JP_JP_#u-ca-japanese, es_SV, pt_BR, mni_IN_#Beng, ml_IN, hr, lt, ccp, zh_CN_#Hans, en, guz_KE, ccp_BD, ca, pa_PK, ug_CN, ki_KE_#Latn, es_BR, bo_CN_#Tibt, chr_US, nyn, mk, sat, pa__#Arab, bs, fy, th, dav_KE, dje, mas_KE, mni_IN, ckb, bem, da, wae, ig, en_HK, brx_IN_#Deva, mer_KE_#Latn, en_US_#Latn, ki, nb, kok, ewo, nn, bg, kea, zu, am_ET, bo_CN, hsb, kok_IN_#Deva, sat_IN, pcm, sah, mer, br, ar_SA, fil_PH_#Latn, sk, om_ET_#Latn, ml, en_MT, en_IL, sv, kn_IN_#Knda, lkt_US, sd__#Deva, ku, fil_PH, es_PH, es_CO, agq, ebu, es_GT, nd_ZW_#Latn, mn, kam_KE, en_MO, ja_JP_#Jpan, wo, shi__#Tfng, en_BZ, lkt_US_#Latn, ta_IN_#Taml, az__#Cyrl, tk, shi__#Latn, en_BW, he_IL, nd_ZW, luy_KE_#Latn, mni__#Beng, ne, zh_SG, om_ET, lo_LA_#Laoo, ja_JP, kam_KE_#Latn, my, ka, ko_KR_#Kore, ms_ID, shi, kl, sa_IN, yue_HK, id, zh, es_PE, mgh_MZ, saq, zh_HK_#Hant, sat_IN_#Olck, es_PA, bez, kw, vai__#Latn, ksh, ur_IN, ln, luy_KE, pt, mgh_MZ_#Latn, ar_YE, to, et, rof, en_BS, be, gv, kln_KE_#Latn, dua, hi_IN_#Deva, guz, en_KE, mfe, ja, or, brx, mai_IN, ko_KR, es_MX, zu_ZA_#Latn, doi_IN, fi, uz, bs__#Cyrl, sr__#Latn, bo_IN, rm, bn, kn, nnh, bn_BD, en_ZA, pa_IN, en_MH, zh__#Hant, jv_ID_#Latn, ky, mas, xh_ZA_#Latn, dav_KE_#Latn, xh, te_IN, mas_KE_#Latn, lrc, ce, mt_MT, ko, ml_IN_#Mlym, ak, kde, dz, ia, seh_MZ, su_ID, ii_CN, pa_PK_#Arab, bn_IN, pa, rwk, rn, tg, hu, ceb_PH_#Latn, twq, bm, en_GU, tr, es_PY, kok_IN, dz_BT_#Tibt, en_PH, zh_MO_#Hans, sat__#Olck, ff, haw_US_#Latn, en_AG, ebu_KE, xog, ms, ug, qu_PE_#Latn, id_ID, teo_KE, haw_US, vi, fr_CA, dyo, luo_KE, eo, en_ZW, pl, ur, uz__#Arab, saq_KE, se, sn_ZW_#Latn, ms_SG, yue__#Hant, km_KH_#Khmr, luy, uk, es_PR, mzn, tt, ug_CN_#Arab, hi_IN, saq_KE_#Latn, asa, ff__#Latn, doi_IN_#Deva, ebu_KE_#Latn, uz__#Cyrl, fil, yue_HK_#Hant, fo, ne_NP, ta_IN, lkt, id_ID_#Latn, is, te_IN_#Telu, si, jv_ID, ks, zh_TW_#Hant, as_IN, zh_HK, sw_KE, th_TH, as_IN_#Beng, jmc, yue, ar, en_VI, haw, bas, uz__#Latn, sg, km_KH, nl, ks_IN_#Arab, sd_IN_#Deva, mr_IN_#Deva, sr, seh_MZ_#Latn, en_CA, gd, chr_US_#Cher, or_IN_#Orya, so_ET, vun, en_IN, lu, yo, es_NI, ii_CN_#Yiii, sd_PK, ti, ccp_IN],
WeekFields[SUNDAY,4]=[pt_PT]}

Originally published at https://stepniewski.tech.

All code examples from this post you will find at my github

Plain Kafka Consumer in Play Framework

psstepniewski — Sun, 26 Dec 2021 18:04:18 +0000

Introduction

I will describe how to use plain Kafka Consumer in Play Framework (Kafka Producer is out of the scope of this post). Please, be aware you can easily find libraries offering API which can better suit to your needs. For example Alpakka provides reactive and stream-aware API. But before you start with more advanced solutions it's always worth to get to know how plain component works.

Start by adding apache kafka dependency to your build.sbt file:

libraryDependencies += "org.apache.kafka" % "kafka-clients" % "3.0.0"

Eager Singleton

Firstly, I will create SampleKafkaCustomer class according to kafka documentation and I will annotate it with javax.inject.Singletion annotation. SampleKafkaCustomer is as simple as possible: it polls messages every 3 seconds from kafka server exposed at localhost:6003 (if you use default configuration it probably is localhost:9092). Kafka Message consists of two parts: key and value. In our example I assume both are simple String (but they can have more complex structure, for example described in json format). SampleKafkaConsumer subscribes sample-topic topic and has assigned sample-group-id consumer group id.

@Singleton
class SampleKafkaConsumer extends Logging {

  logger.info("Starting SampleKafkaConsumer")

  private  val properties = new Properties()
  properties.put("bootstrap.servers", "localhost:6003")
  properties.put("group.id", s"sample-group-id")
  properties.put("key.deserializer", classOf[StringDeserializer])
  properties.put("value.deserializer", classOf[StringDeserializer])

  val kafkaConsumer = new KafkaConsumer[String, String](properties)
  kafkaConsumer.subscribe(Set("sample-topic").asJava)

  Try {
    while (true) {
      kafkaConsumer.poll(Duration.ofSeconds(3)).asScala
        .foreach(r => {
          logger.info(s"SampleKafkaConsumer receive record $r")
        })
    }
  } match {
    case Success(_) => logger.info(s"SampleKafkaConsumer succeed.")
    case Failure(e) => logger.error(s"SampleKafkaConsumer fail.", e)
  }
}

I want to start up Kafka Consumer when application starts. This type of requirements can be easily satisfied using eager singleton. To do this I will define play module which will mark SampleKafkaConsumer singleton as eager:

class KafkaModule extends AbstractModule with Logging {

  override def configure(): Unit = {
    logger.info("Starting KafkaModule")
    bind(classOf[SampleKafkaConsumer]).asEagerSingleton()
  }
}

To start KafkaModule it must be enabled in play configuration (by default it is application.conf file):

play.modules.enabled += "kafka.KafkaModule

If you now start application you will notice that it is not starting :) In logs everything is looking ok:

--- (Running the application, auto-reloading is enabled) ---

[info] p.c.s.AkkaHttpServer - Listening for HTTP on /0:0:0:0:0:0:0:0:9000

Server started, use Alt+D to stop

But after opening desired localization in browser (in my case http://localhost:9000) , the page is still loading all the time. It is because SampleConsumerKafka contains while(true) loop in which consumer polls Kafka messages every 3 seconds. As a result SampleConsumerKafka constructor never finish and application can't start. To resolve this problem I will run while(true) loop in asynchronous manner.

Polling in dedicated thread-pool

To allow application start I will add dedicated thread for KafkaConsumer logic (while(true) loop). KafkaConsumer loop uses single thread anyway, so it is a good idea to create dedicated ExecutionContext for this purpose. In the following listing I don't mark ExecutionContext implicit, that you can follow how it is used. I also replaced Try code block with Future code block.

@Singleton
class SampleKafkaConsumer extends Logging {

  logger.info("Starting SampleKafkaConsumer")

  val executionContext: ExecutionContext = ExecutionContext.fromExecutor(Executors.newSingleThreadExecutor())

  private val properties = new Properties()
  properties.put("bootstrap.servers", "localhost:6003")
  properties.put("group.id", s"sample-group-id")
  properties.put("key.deserializer", classOf[StringDeserializer])
  properties.put("value.deserializer", classOf[StringDeserializer])

  val kafkaConsumer = new KafkaConsumer[String, String](properties)
  kafkaConsumer.subscribe(Set("sample-topic").asJava)

  Future {
    while (true) {
      kafkaConsumer.poll(Duration.ofSeconds(3)).asScala
        .foreach(r => {
          logger.info(s"SampleKafkaConsumer receive record $r")
        })
    }
  }(executionContext).andThen {
    case Success(_) => logger.info(s"SampleKafkaConsumer succeed.")
    case Failure(e) => logger.error(s"SampleKafkaConsumer fail.", e)
  }(executionContext)
}

Now it works great! ...almost. Application starts, but I need to do one thing more. KafkaConsumer is never closed, even if application stops!

Stopping KafkaConsumer

KafkaConsumer is not thread-safe, so I need to stop it in the same thread as while(true) loop runs. To do it I must define loop quit condition. I will follow kafka documentation and I will add AtomicBoolean field to keep information if consumer should be stopped (default field value is set to false). If while(!stopConsumer.get()) loop will quit, KafkaConsumer will stop.

@Singleton
class SampleKafkaConsumer extends Logging {

  logger.info("SampleKafkaConsumer starts")

  private val executionContext: ExecutionContext = ExecutionContext.fromExecutor(Executors.newSingleThreadExecutor())
  private val stopConsumer: AtomicBoolean = new AtomicBoolean(false)

  private val properties = new Properties()
  properties.put("bootstrap.servers", "localhost:6003")
  properties.put("group.id", s"sample-group-id")
  properties.put("key.deserializer", classOf[StringDeserializer])
  properties.put("value.deserializer", classOf[StringDeserializer])

  val kafkaConsumer = new KafkaConsumer[String, String](properties)
  kafkaConsumer.subscribe(Set("sample-topic").asJava)

  Future {
    while (!stopConsumer.get()) {
      kafkaConsumer.poll(Duration.ofSeconds(3)).asScala
        .foreach(r => {
          logger.info(s"SampleKafkaConsumer receives record: $r")
        })
    }
    logger.info(s"SampleKafkaConsumer quits 'while(true)' loop.")
  }(executionContext)
  .andThen(_ => kafkaConsumer.close())(executionContext)
  .andThen {
    case Success(_) =>
      kafkaConsumer.close()
    case Failure(e) =>
      kafkaConsumer.close()
  }(executionContext)
}

All I need to do now is change stopConsumer flag value from false to true during application stop. Play Framework provides CoordinatedShutdown component to such requirements, which originally is Akka solution (Play Framework is build on Akka). CoordinatedShutdown allows you to define tasks to be executed during the shutdown process. It is more flexible component than earlier used ApplicationLifecycle component. ApplicationLifecycle is not deprecated (you can use it instead), it just offers you possibility to add task in only one phase of shutdown process - phase named service-stop. I need to add stop task to exactly this phase, but I chose to use CoordinatedShutdown. The task will change stopConsumer flag value to true.

coordinatedShutdown.addTask(CoordinatedShutdown.PhaseServiceStop, "SampleKafkaConsumer-stop"){() =>
    logger.info("Shutdown-task[SampleKafkaConsumer-stop] starts.")
    stopConsumer.set(true)
    Future{ Done }(executionContext).andThen{
      case Success(_) => logger.info("Shutdown-task[SampleKafkaConsumer-stop] succeed.")
      case Failure(e) => logger.error("Shutdown-task[SampleKafkaConsumer-stop] fails.", e)
    }(executionContext)
  }

Pay attention added task returns Future{ Done } using defined earlier executionContext. It gives confidence, that Future will complete after while loop quits and KafkaConsumer stops (executionContext contains single thread, so it must quit loop first to do something else). Please, be also aware that every phase of shutdown process has timeout after which next phase begin, even if current phase didn’t end. Default service-stop phase timeout is 5 seconds. Final version of SampleKafkaConsumer

@Singleton
class SampleKafkaConsumer @Inject()(coordinatedShutdown: CoordinatedShutdown) extends Logging {

  logger.info("SampleKafkaConsumer starts")

  private val executionContext: ExecutionContext = ExecutionContext.fromExecutor(Executors.newSingleThreadExecutor())
  private val stopConsumer: AtomicBoolean = new AtomicBoolean(false)

  private val properties = new Properties()
  properties.put("bootstrap.servers", "localhost:6003")
  properties.put("group.id", s"sample-group-id")
  properties.put("key.deserializer", classOf[StringDeserializer])
  properties.put("value.deserializer", classOf[StringDeserializer])

  val kafkaConsumer = new KafkaConsumer[String, String](properties)
  kafkaConsumer.subscribe(Set("sample-topic").asJava)

  Future {
    while (!stopConsumer.get()) {
      kafkaConsumer.poll(Duration.ofSeconds(3)).asScala
        .foreach(r => {
          logger.info(s"SampleKafkaConsumer receives record: $r")
        })
    }
    logger.info(s"SampleKafkaConsumer quits 'while(true)' loop.")
  }(executionContext)
  .andThen(_ => kafkaConsumer.close())(executionContext)
  .andThen {
    case Success(_) =>
      logger.info(s"SampleKafkaConsumer succeed.")
    case Failure(e) =>
      logger.error(s"SampleKafkaConsumer fails.", e)
  }(executionContext)

  coordinatedShutdown.addTask(CoordinatedShutdown.PhaseServiceStop, "SampleKafkaConsumer-stop"){() =>
    logger.info("Shutdown-task[SampleKafkaConsumer-stop] starts.")
    stopConsumer.set(true)
    Future{ Done }(executionContext).andThen{
      case Success(_) => logger.info("Shutdown-task[SampleKafkaConsumer-stop] succeed.")
      case Failure(e) => logger.error("Shutdown-task[SampleKafkaConsumer-stop] fails.", e)
    }(executionContext)
  }
}

Some logs

When application starts you will find log:

[info] k.SampleKafkaConsumer play-dev-mode-akka.actor.default-dispatcher-7 - SampleKafkaConsumer starts

Now, I will start command line KafkaProducer and I will send some messages to sample-topic topic:

$ bin/kafka-console-producer.sh --topic sample-topic --bootstrap-server localhost:6003
>Hello Readers!
>Thank you!

SampleKafkaConumer logs all messages:

[info] k.SampleKafkaConsumer pool-10-thread-1 - SampleKafkaConsumer receives record: ConsumerRecord(topic = sample-topic, partition = 0, leaderEpoch = 0, offset = 0, CreateTime = 1640519882833, serialized key size = -1, serialized value size = 15, headers = RecordHeaders(headers = [], isReadOnly = false), key = null, value = Hello Readers!)
[info] k.SampleKafkaConsumer pool-10-thread-1 - SampleKafkaConsumer receives record: ConsumerRecord(topic = sample-topic, partition = 0, leaderEpoch = 0, offset = 1, CreateTime = 1640519898470, serialized key size = -1, serialized value size = 9, headers = RecordHeaders(headers = [], isReadOnly = false), key = null, value = Thank you!)

Now I will stop application (PID=26054) with SIGTERM:

kill 26054

SampleKafkaConsumer stops gracefully:

[info] p.c.s.AkkaHttpServer play-dev-mode-shutdown-hook-1 - Stopping Akka HTTP server...
[info] p.c.s.AkkaHttpServer play-dev-mode-akka.actor.internal-dispatcher-2 - Terminating server binding for /0:0:0:0:0:0:0:0:9000
[info] s.ApplicationTimer application-akka.actor.internal-dispatcher-5 - ApplicationTimer demo: Stopping application at 2021-12-26T11:58:35.988474Z after 129s.
[info] k.SampleKafkaConsumer application-akka.actor.internal-dispatcher-5 - Shutdown-task[SampleKafkaConsumer-stop] starts.
[info] k.SampleKafkaConsumer pool-10-thread-1 - SampleKafkaConsumer quits 'while(true)' loop.
[info] o.a.k.c.c.i.ConsumerCoordinator pool-10-thread-1 - [Consumer clientId=consumer-sample-group-id-1, groupId=sample-group-id] Revoke previously assigned partitions sample-topic-0
[info] o.a.k.c.c.i.ConsumerCoordinator pool-10-thread-1 - [Consumer clientId=consumer-sample-group-id-1, groupId=sample-group-id] Member consumer-sample-group-id-1-52faa9ac-a6c3-42e5-99aa-33c992070bea sending LeaveGroup request to coordinator localhost:6003 (id: 2147483646 rack: null) due to the consumer is being closed
[info] o.a.k.c.c.i.ConsumerCoordinator pool-10-thread-1 - [Consumer clientId=consumer-sample-group-id-1, groupId=sample-group-id] Resetting generation due to: consumer pro-actively leaving the group
[info] o.a.k.c.c.i.ConsumerCoordinator pool-10-thread-1 - [Consumer clientId=consumer-sample-group-id-1, groupId=sample-group-id] Request joining group due to: consumer pro-actively leaving the group
[info] o.a.k.c.m.Metrics pool-10-thread-1 - Metrics scheduler closed
[info] o.a.k.c.m.Metrics pool-10-thread-1 - Closing reporter org.apache.kafka.common.metrics.JmxReporter
[info] o.a.k.c.m.Metrics pool-10-thread-1 - Metrics reporters closed
[info] o.a.k.c.u.AppInfoParser pool-10-thread-1 - App info kafka.consumer for consumer-sample-group-id-1 unregistered
[info] k.SampleKafkaConsumer pool-10-thread-1 - SampleKafkaConsumer succeed.
[info] k.SampleKafkaConsumer pool-10-thread-1 - Shutdown-task[SampleKafkaConsumer-stop] succeed.
[info] p.c.s.AkkaHttpServer play-dev-mode-akka.actor.internal-dispatcher-15 - Running provided shutdown stop hooks

Summary

In this post I described how to use plain KafkaConsumer in Play Framework. It is always worth to know how lower-level components works, but after all I strongly encourage you to consider use libraries like Alpakka. For example in my last project I decided to use akka-projection which is build on Alpakka. It composes with Akka nicely and give you some extra value like easy configuration of restart strategy in case of failure.

All code examples from this post you will find at my github. If you want to follow code changes section after section, check git log. Every commit corresponds to single post section.

Originally published at https://stepniewski.tech

java.time can be tricky. Know it better!

psstepniewski — Sun, 05 Dec 2021 18:46:28 +0000

Motivation

Recently, when I was implementing system module, I temporarily had used database mocks. Later, when I replaced mocks with real database I got UnsupportedOperationException on java.util.Date#toInstant calls. It made me realize: I need to get to know java.time package better.

java.time package

java.time package contains few classes to represent date or time, the main are:

Instant - point on the time-line, stores number of seconds since 1970-01-01T00:00:00Z (epoch) and nanoseconds part of second,
LocalDate - represents only date,
LocalTime - represents only time (with nanoseconds precision),
LocalDateTime - represents date and time,
OffsetDateTime - represents date, time and zone offset,
ZonedDateTime - represents date, time, zone offset and time zone.

In simplification, it can be illustrated as the following:

Start testing!

Good way to know these classes better is to write few tests. You can find all my tests on github.

Parsing java.sql objects to java.time.Instant

UnsupportedOperationException about which I wrote in the Motivation section was thrown while parsing from java.sql package class to java.time package class. java.sql package contains three main classes:

Date - represents only date,
Time - represents only time,
Timestamp - represents date and time.

Tests show, that the following assertions are true. These two toInstant calls throw UnsupportedOperationException.

Date sqlDate = new java.sql.Date(Instant.now().toEpochMilli());
assertThrows(UnsupportedOperationException.class, sqlDate::toInstant);

Date sqlTime = new java.sql.Time(Instant.now().toEpochMilli());
assertThrows(UnsupportedOperationException.class, sqlTime::toInstant);

But the following code will execute without any Exception.

Date sqlTimestamp = new java.sql.Timestamp(Instant.now().toEpochMilli());
assertDoesNotThrow(sqlTimestamp::toInstant);

Date from java.sql has no time part (in contrast to result of new java.util.Date() call), so it cannot be parsed to Instant
java.sql.Date#toInstant doesn't assume that 2021-07-18 means 2021-07-18 00:00:00.000, the time part is simply unknown.
Similarly Time has no date part. Only Timestamp has specified both parts: date and time, so it can be translated to Instant.

There is one tricky thing. All mentioned java.sql classes are child of java.util.Date. java.util.Date can be understood as numer of milliseconds since 1970-01-01T00:00:00Z (epoch). java.util.Date implements toInstant method.If you (like me) will use database mocks which return java.util.Date and you will use java.util.Date#toInstant method, then after switching to real database you may be surprised by UnsupportedOperationException. It is because your database access solution (like Hibernate) can put java.sql.Date (which doesn't implement toInstant method) under java.util.Date reference (which implements toInstant method)! For example, It will happen if you use @Temporal(TemporalType.Date) JPA annotation.

Parsing String to java.time objects

java.time introduces DateTimeFormatter class which supports bidirectional translations between String and java.time objects. It is similar to SimpleDateFormat class, but comparing to it DateTimeFormatter is thread-safe. Let's assume we want to parse String "2021-12-03T10:15:30Z" (contains date, time and zone offset; Z is equal to +0000 offset) to main java.time classes, all the following assertions are true:

final String toParse = "2021-12-03T10:15:30Z";
inal DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ssX");

assertDoesNotThrow(() -> formatter.parse(toParse, Instant::from));
assertDoesNotThrow(() -> LocalTime.parse(toParse, formatter));
assertDoesNotThrow(() -> LocalDate.parse(toParse, formatter));
assertDoesNotThrow(() -> LocalDateTime.parse(toParse, formatter));
assertDoesNotThrow(() -> OffsetDateTime.parse(toParse, formatter));
assertDoesNotThrow(() -> ZonedDateTime.parse(toParse, formatter));

assertEquals(LocalTime.parse(toParse, formatter), LocalTime.of(10, 15, 30, 0));
assertEquals(LocalDate.parse(toParse, formatter), LocalDate.of(2021, 12, 3));
assertEquals(LocalDateTime.parse(toParse, formatter), LocalDateTime.of(2021, 12, 3, 10, 15, 30, 0));
assertEquals(OffsetDateTime.parse(toParse, formatter), OffsetDateTime.of(2021, 12, 3, 10, 15, 30, 0, ZoneOffset.of("Z")));
assertEquals(ZonedDateTime.parse(toParse, formatter), ZonedDateTime.of(2021, 12, 3, 10, 15, 30, 0, ZoneId.of("Z")));

Pay attention that if you parse String to poorer java.time object you can lose information, but an Exception is not thrown! After parsing String "2021-12-03T10:15:30Z" to LocalDate you will keep information only about date and time, offset will be lost.

On the other hand if you try to parse String "2021-12-03T10:15:30" (contains date and time but not offset) to broader java.time object you will get DateTimeParseException. The following assertions are true:

final String toParse = "2021-12-03T10:15:30";
final DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss");

assertThrows(DateTimeParseException.class, () -> formatter.parse(toParse, Instant::from));
assertThrows(DateTimeParseException.class, () -> OffsetDateTime.parse(toParse, formatter));
assertThrows(DateTimeParseException.class, () -> ZonedDateTime.parse(toParse, formatter));

Interesting thing is that java.time.ZoneId class is parent of java.time.ZoneOffset class. The following assertions are true:

final String toParse = "2021-12-03T10:15:30-08";
final DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ssX");

assertDoesNotThrow(() -> ZonedDateTime.parse(toParse, formatter)); // ZoneOffset (-08) as ZoneId
assertEquals(ZonedDateTime.parse(toParse, formatter), ZonedDateTime.of(2021, 12, 3, 10, 15, 30, 0, ZoneOffset.of("-08")));

Be aware that to get Instant class from other java.time objects you need to provide information about offset. ZonedDateTime and OffsetDateTime keep this information, but if you will use for example LocalDateTime you must provide zone definition in LocalDateTime#toInstant call.
In simplification Instant is number of nanoseconds since 1970-01-01T00:00:00Z(UTC), so to get Instant object you need to know ZoneOffset. java.time.DateTimeFormatter#parse will not use UTC or your system ZoneOffset by default. The following assertions
are true:

final String toParse = "2021-12-03T10:15:30"; //ZoneId is not provided
final DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss");

assertThrows(DateTimeParseException.class, () -> formatter.parse(toParse, Instant::from)); //Instant must know ZoneId
assertDoesNotThrow(() -> LocalDateTime.parse(toParse, formatter).toInstant(ZoneOffset.UTC)); //ZoneId provided in toInstant call

Last test, if you try to parse String which not match to DateTimeFormatter pattern you will get exception, even if your String is broader than given DateTimeFormatter pattern. For example if you try parse String equals to 2021-12-03T10:15:30Z with DateTimeFormatter pattern equals to yyyy-MM-dd'T'HH:mm:ss (comparing to parsed String pattern does not handle zone offset) you will get exception. The following assertion is true:

final String toParse = "2021-12-03T10:15:30Z";
final DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss");

assertThrows(DateTimeParseException.class, () -> formatter.parse(toParse));

comparing java.time package objects

Be aware if you cast between java.time objects you can lose information. For example if you call java.time.OffsetDateTime#toLocalDateTime() on two object which has equal date and time but different offsets, the returned LocalDateTime will be equal (zone offset data will be lost). The following assertion is true:

OffsetDateTime offsetDateTime1 = OffsetDateTime.of(2021, 11, 10, 10, 11, 12, 0, ZoneOffset.of("+01"));
OffsetDateTime offsetDateTime2 = OffsetDateTime.of(2021, 11, 10, 10, 11, 12, 0, ZoneOffset.of("+05"));
assertEquals(offsetDateTime1.toLocalDateTime(), offsetDateTime2.toLocalDateTime());

If you want to compare two java.time objects as points in time, the best choice is Instant class. For example if you have two OffsetDateTime objects which represents the same point in time but with different zone offsets (both 2021-11-10 10:11:12.000+01 and 2021-11-10 15:11:12.000+06 represents the same point in time equals to 2021-11-10 09:11:12+00) they will be not equal. OffsetDateTime#equals does not compare points in time but check if compared objects have equal dates, times and zone offsets. To compare point in times use Instant class instead. The following assertions are true (all the following offset variables represent the same point in time equal to 2021-11-10T09:11:12Z):

OffsetDateTime offset1 = OffsetDateTime.of(2021, 11, 10, 10, 11, 12, 0, ZoneOffset.of("+01"));
OffsetDateTime offset2 = OffsetDateTime.of(2021, 11, 10, 15, 11, 12, 0, ZoneOffset.of("+06"));
OffsetDateTime offset3 = OffsetDateTime.of(2021, 11, 10, 10, 11, 12, 0, ZoneOffset.of("+01"));

assertEquals(offset1.toInstant(), offset2.toInstant());
assertNotEquals(offset1, offset2);
assertEquals(offset1, offset3);

Differences between ZonedDateTime and OffsetDateTime can be not clear at the beginning. Main difference is ZonedDateTime can switch its zone offset. For example in Poland (Europe/Warsaw time zone) two zone offsets are used: +02 offset is used in the Summer (from the end of March to the end of October) and +01 offset is used in the Winter (from the end of October to the end of March). Two zone offsets requires time change, one of them took place on 25.10.2020: time was set back from 3 am to 2 am. Consequently, the following assertions are true:

ZonedDateTime zonedDateTime1 = ZonedDateTime.of(2020, 10, 25, 2, 0, 0, 0, ZoneId.of("Europe/Warsaw"));
assertEquals(zonedDateTime1.plusHours(1).toLocalDateTime(), zonedDateTime1.toLocalDateTime());

assertNotEquals(zonedDateTime1.plusHours(1).getOffset(), zonedDateTime1.getOffset());

ZonedDateTime keep information about ZoneOffset so it is aware whether time has been set back.

And it's all. I hope after reading this post you know java.time package better :)

Originally published at https://stepniewski.tech.

How to model result?

psstepniewski — Sun, 21 Nov 2021 11:42:22 +0000

Introduction

Method call often returns some result. For example let's assume we have method which creates new object: Payment. Now imagine Payment creation fails because passed amount is negative. In this case our method can just throw IllegalArgumentException. So far we have two possible method results:

returned Payment instance
thrown IllegalArgumentException.

It was a simple example, I will complicate it a little. Let's assume we already have Payment instance, and it is a specific payment type - CardPayment. New CardPayment instance represents only intention to collect money. CardPayment provides execute method which calls external service to realize cash flow. What are possible results? Same as before we can get some object - information about successful payment. Method could also throw an Exception if external service fails or it is not accessible (timeout for example). But CardPayment can fail also for many business reasons: client has no fund on the card, payment exceeded single transaction amount limit, payment exceeded daily transactions amounts sum limit or card has been blocked. These results are regular and common situations, so they shouldn't be model by throwing an Exception. Better choice is to design the execute() method interface which covers all described cases. How to model many possible business results?

Disclaimer: I consider only method synchronous result. Asynchronous solutions like event publish/subscribe is
out of the scope of this post.

Problem

Let's summarize all possible results of described above CardPayment#execute method:

success execution - payment made correctly, result contains external system success payment id,
client has no fund on the card - result contains datetime field named nextTryAfter, all future card payments before this date will be rejected by external service
payment exceeded single transaction maximum amount limit - result contains field singleTransactionLimit which is value of exceeded limit value,
payment exceeded daily transactions amounts sum limit - result contains field dailySumLimit which is value of exceeded limit value,
card has been blocked - result contains external system blocked card id.

Our goal is to model all possible business results of the execute method.

Single class for all cases

In the simplest solution all above results can be designed with single class, for example:

public class Example1 {

    record CardPaymentResult(String resultCode,
                             String successPaymentId,
                             LocalDateTime nextTryAfter,
                             BigInteger singleTransactionLimit,
                             BigInteger dailySumLimit,
                             String blockedCardId) {}

    public void example1() {
        // success execution - payment made correctly
        new CardPaymentResult("PAYMENT_OK", "vanoh5ailuChay6p", null, null, null, null);
        // client has no fund on the card,
        new CardPaymentResult("CLIENT_HAS_NO_FUND", null, LocalDateTime.of(2021, 11, 30, 10, 0, 0), null, null, null);
        // payment exceeded single transaction maximum amount limit,
        new CardPaymentResult("SINGLE_TRANSACTION_LIMIT_EXCEEDED", null, null, BigInteger.valueOf(20000), null, null);
        // payment exceeded daily transactions amounts sum limit,
        new CardPaymentResult("DAILY_TRANSACTIONS_LIMIT_EXCEEDED", null, null,null, BigInteger.valueOf(50000), null);
        // card has been blocked.
        new CardPaymentResult("CARD_BLOCKED", null, null,null, null, "eoZi5chu");
    }
}

In the above listing I use record Java keyword introduced in Java 14. Thanks to it, the Java compiler auto generates getter methods, toString(), hashcode() and equals() methods, so you don't have to write that boilerplate code yourself. Java record is immutable, no setter methods are generated.

You can easily find disadvantages of this solution:

CardPaymentResult has many fields and every resultCode can increase theirs number.
It is hard to predict which field are nulls. CardPaymentResult contains many nullable fields which presence depends on resultCode. It is easy to make mistake and get famous NullPointerException. Moreover, when you meet CardPaymentResult reference in code you can't simply predict what resultCodes are possible in given context and which fields can be nulls. For example, you must discover context like "scheduling next payment after failure" to know that you are dealing with CLIENT_HAS_NO_FUND, SINGLE_TRANSACTION_LIMIT_EXCEEDED or DAILY_TRANSACTIONS_LIMIT_EXCEEDED because for other resultCodes there is no sense to retry with new payment (PAYMENT_OK - we already succeed, we don't need to retry, CARD_BLOCKED - we are sure all future retries will fail). It is also possible you pass by mistake instance of CardPaymentResult with resultCode which should never be present in given context.
In every case when you need to handle one resultCode in unique way you need to add if condition to check if you deal with this unique resultCode.

We definitely can design it better.

Class per case

Second solution is to create dedicated class for every result case.

public class Example2 {

    interface Result {}
    interface Results {
        record PaymentOk(String resultCode, String successPaymentId) implements Result {}
        record ClientHasNoFund(String resultCode, LocalDateTime nextTryAfter) implements Result {}
        record SingleTransactionLimitExceeded(String resultCode, BigInteger singleTransactionLimit) implements Result {}
        record DailyTransactionsLimitExceeded(String resultCode, BigInteger dailySumLimit) implements Result {}
        record CardBlocked(String resultCode, String blockedCardId) implements Result {}
    }

    public void example2() {
        // success execution - payment made correctly
        new Results.PaymentOk("PAYMENT_OK", "vanoh5ailuChay6p");
        // client has no fund on the card,
        new Results.ClientHasNoFund("CLIENT_HAS_NO_FUND", LocalDateTime.of(2021, 11, 30, 10, 0, 0));
        // payment exceeded single transaction maximum amount limit,
        new Results.SingleTransactionLimitExceeded("SINGLE_TRANSACTION_LIMIT_EXCEEDED", BigInteger.valueOf(20000));
        // payment exceeded daily transactions amounts sum limit,
        new Results.DailyTransactionsLimitExceeded("DAILY_TRANSACTIONS_LIMIT_EXCEEDED", BigInteger.valueOf(50000));
        // card has been blocked.
        new Results.CardBlocked("CARD_BLOCKED", "eoZi5chu");
    }
}

Pay attention that every possible result implements Result interface. Moreover, all Result descendant are grouped in Results interface. Thanks to it, if you will start typing Example2.Results. IDE will prompt with all possible Results.

Comparing to the previous solution:

There are five classes with small number of fields instead of one big class with many fields. If new resultCode appears, instead of modifying one big class a new small class will be defined. It is compatible with principle "open for extension, closed for modification".
You are not dealing with null fields. In every case all fields are not-null. Moreover, you can use specific class instead of general Result type to be sure that type with proper resultCode is used in given context.
You still will need to use if condition to handle specific resultCode in unique way if you deal with Result type. But now it is possible that you will deal with specific type like PaymentOk, it won't be always general Result type. Moreover, Java 17 introduces pattern matching for switch condition, which improves code readability, for example:

public static class PatternMatchingExample {

    public Message messageFor(Result result) {
        return switch (result) {
            case Results.PaymentOk v                      -> paymentOkMessage(v);
            case Results.ClientHasNoFund v                -> clientHasNoFund(v);
            case Results.SingleTransactionLimitExceeded v -> singleTransactionLimitExceeded(v);
            case Results.DailyTransactionsLimitExceeded v -> dailyTransactionsLimitExceeded(v);
            case Results.CardBlocked v                    -> cardBlocked(v);
            default                                       -> defaultMessage();
        };
    }
}

Before Java 17 you probably would use sequence of instanceof if conditions:

public class InstanceOfExample {
    public Message messageFor(Result result) {
        if(result instanceof Results.PaymentOk) {
            return paymentOkMessage((Results.PaymentOk) result);
        }
        else if(result instanceof Results.ClientHasNoFund) {
            return clientHasNoFund((Results.ClientHasNoFund) result);
        }
        else if(result instanceof Results.SingleTransactionLimitExceeded) {
            return singleTransactionLimitExceeded((Results.SingleTransactionLimitExceeded) result);
        }
        else if(result instanceof Results.DailyTransactionsLimitExceeded) {
            return dailyTransactionsLimitExceeded((Results.DailyTransactionsLimitExceeded) result);
        }
        else if(result instanceof Results.CardBlocked) {
            return cardBlocked((Results.CardBlocked) result);
        }
        else {
            return defaultMessage();
        }
    }
}

Little note: some programmers say that using instanceof keyword always breaks polymorphism concept. I disagree with this opinion. According to wikipedia:

In programming languages and type theory, polymorphism is the provision of a single interface to entities of different types[1] or the use of a single symbol to represent multiple different types.[2]The concept is borrowed from a principle in biology where an organism or species can have many different forms or stages.[3]

In this case you deal with classes which represent results, not a behaviors. Their goal is to carry data, not perform actions. They are not have any id, they just are simple data structures. Our classes are not entities, but value objects.

Other options...

Above solution is good for case when action has many results which contains different data (successPaymentId or nextTryAfter or singleTransactionLimit or dailySumLimit or blockedCardId). But this solution not always fit best. If your component returns many results but their data are not needed, you can use enum type instead of a collection
of classes, for example:

public class Example3 {

    public enum Result {
        PAYMENT_OK, CLIENT_HAS_NO_FUND, SINGLE_TRANSACTION_LIMIT_EXCEEDED, DAILY_TRANSACTIONS_LIMIT_EXCEEDED, CARD_BLOCKED
    }

    public class PatternMatchingExample {

        public Message messageFor(Result result) {
            return switch (result) {
                case PAYMENT_OK                        -> paymentOkMessage();
                case CLIENT_HAS_NO_FUND                -> clientHasNoFund();
                case SINGLE_TRANSACTION_LIMIT_EXCEEDED -> singleTransactionLimitExceeded();
                case DAILY_TRANSACTIONS_LIMIT_EXCEEDED -> dailyTransactionsLimitExceeded();
                case CARD_BLOCKED                      -> cardBlocked();
                default                                -> defaultMessage();
            };
        }
    }
}

If your component returns only two different results you can use abstraction like Either class from vavr.io (javaslang) library:

import io.vavr.control.Either;

public class Example4 {

    record PaymentOk(String resultCode, String successPaymentId) implements Example2.Result {}
    record PaymentFail(String resultCode, String failReason) implements Example2.Result {}

    public Either<PaymentFail, PaymentOk> example4() {
        //omitted code
        return Either.right(new PaymentOk("PAYMENT_OK", "vanoh5ailuChay6p"));
    }
}

Finally, if you have component with many results which have similar structure, the solution with single class for all cases (described at the beginning of this post) may fit best. You always can refactor it later when complexity will increase.

There just not exists the best solution for every case, everything depends on problem details. In this post I wanted to describe few approaches how you can model many business results. It is common problem and I hope you will feel a little more comfortable with it after this post.

All Java examples from this post you will find at my github.

Originally published at https://stepniewski.tech.

From Scala to Java. Encapsulate code with inner static classes, interfaces and enums.

psstepniewski — Sat, 06 Nov 2021 13:48:47 +0000

Using two languages causes you try to apply some concepts from one language to the other. Scala developers often say they started to commonly use final word with class field in Java. Similarly, one language often evolves inspired by other languages. For example, from Java 8 developers can use deafult interface method (similar to Scala trait), from Java 10 there is var keyword for declaring local variables, pattern matching implemented with switch statements gone through a rapid evolution since Java 7.

I would like to share with you how Scala improves my Java code. In this post I will describe why I started commonly use inner static classes, enums and interfaces.

It is common practice to defining every Java class in separated file. You often meet every class, enum and interface placed in dedicated file. Let's start with example. Consider service to customer payments history verification (CustomerVerificationService). It can result with positive or negative loan decision. Verification consists of few steps: first system checks if customer is blacklisted, next if customer has internal debts (in relation to our company), at the end if external services reveals customer debts.

CustomerVerificationService#verifyPaymentHistory can return:

BlackListedCustomer(String reason) - customer is blacklisted, credit decision is negative; result contains reason of blacklisting.
InternalDebt(String agreementNumber, BigInteger debtAmount) - customer isn't blacklisted, but is our company debtor, credit decision is negative; result contains debt agreement number and debt value.
ExternalDebt(String debtSource, BigInteger debtAmount) - customer isn't blacklisted, has no debt in our company but external services reveal debt, credit decision is negative; result contains debt value and its source (external service name).
PositiveDecision(BigInteger maxAmount) - customer is not blacklisted and has no debts (internal or external), credit decision is positive; result contains maximum allowed loan value.

Above service interface can be implemented with Java 11 (LTS) as following:

public class CustomerVerificationService {

  public VerificationResult verifyPaymentHistory(Customer customer) {
    //omitted code
    return new PositiveDecision(BigInteger.valueOf(6000L));
  }
}

public class Customer {
  private final String pesel;
  private final String firstName;
  private final String lastName;
  private final String idNumber;

  public Customer(String pesel, String firstName, String lastName, String idNumber) {
    this.pesel = pesel;
    this.firstName = firstName;
    this.lastName = lastName;
    this.idNumber = idNumber;
  }

  public String getPesel() {
    return pesel;
  }

  public String getFirstName() {
    return firstName;
  }

  public String getLastName() {
    return lastName;
  }

  public String getIdNumber() {
    return idNumber;
  }
}

public interface VerificationResult {
}

public class BlackListedCustomer implements VerificationResult {
  private final String reason;

  public BlackListedCustomer(String reason) {
    this.reason = reason;
  }

  public String getReason() {
    return reason;
  }
}

public class InternalDebt implements VerificationResult {
  private final String agreementNumber;
  private final BigInteger debtAmount;

  public InternalDebt(String agreementNumber, BigInteger debtAmount) {
    this.agreementNumber = agreementNumber;
    this.debtAmount = debtAmount;
  }

  public String getAgreementNumber() {
    return agreementNumber;
  }

  public BigInteger getDebtAmount() {
    return debtAmount;
  }
}

public class ExternalDebt implements VerificationResult {
  private final String debtSource;
  private final BigInteger debtAmount;

  public ExternalDebt(String debtSource, BigInteger debtAmount) {
    this.debtSource = debtSource;
    this.debtAmount = debtAmount;
  }

  public String getDebtSource() {
    return debtSource;
  }

  public BigInteger getDebtAmount() {
    return debtAmount;
  }
}

public class PositiveDecision implements VerificationResult {
  private final BigInteger maxAmount;

  public PositiveDecision(BigInteger maxAmount) {
    this.maxAmount = maxAmount;
  }

  public BigInteger getMaxAmount() {
    return maxAmount;
  }
}

We have here as many as 7 files. Situation is quite different in Scala, single file often contains definition of several classes, objects, traits,case classes. For example:

class CustomerVerificationService {

  def verifyPaymentHistory(customer: Customer): Result = {
    //omitted code
    PositiveDecision(6000)
  }
}

object CustomerVerificationService {

    case class Customer(pesel: String, firstName: String, lastName: String, idNumber: String)

    sealed trait Result
    object Results {
      case class InternalDebt(agreementNumber: String, debtAmount: BigInt) extends Result
      case class ExternalDebt(debtSource: String, debtAmount: BigInt) extends Result
      case class BlackListedCustomer(reason: String) extends Result
      case class PositiveDecision(maxAmount: BigInt) extends Result
    }
}

Apart from the huge difference in code volume, pay attention how Scala example nicely encapsulates service interface. Service CustomerVerificationService has single public method verifyPaymentHistory. In the same file you will find definition of method input: Customer class. Every possible result of this operation is instance of Result trait. Moreover, all Result descendant are grouped in Results object. Thanks to it, if you will start typing CustomerVerificationService.Results. IDE will prompt with all possible Results. Once again, pay attention how comfortably you can get all information about CustomerVerificationService#verifyPaymentHistory. You need to look only into single file. But good news! You can write
in a similar manner in Java! All you need to do is use inner static classes and inner interfaces.

public class CustomerVerificationService {

  public  Result verifyPaymentHistory(Customer customer) {
    //omitted code
    return new Results.PositiveDecision(BigInteger.valueOf(6000L));
  }

  public static class Customer {
    private final String pesel;
    private final String firstName;
    private final String lastName;
    private final String idNumber;

    public Customer(String pesel, String firstName, String lastName, String idNumber) {
      this.pesel = pesel;
      this.firstName = firstName;
      this.lastName = lastName;
      this.idNumber = idNumber;
    }

    public String getPesel() {
      return pesel;
    }

    public String getFirstName() {
      return firstName;
    }

    public String getLastName() {
      return lastName;
    }

    public String getIdNumber() {
      return idNumber;
    }
  }

  public interface Result { }
  public interface Results {
    class BlackListedCustomer implements Result {
      private final String reason;

      public BlackListedCustomer(String reason) {
        this.reason = reason;
      }

      public String getReason() {
        return reason;
      }
    }
    class InternalDebt implements Result {
      private final String agreementNumber;
      private final BigInteger debtAmount;

      public InternalDebt(String agreementNumber, BigInteger debtAmount) {
        this.agreementNumber = agreementNumber;
        this.debtAmount = debtAmount;
      }

      public String getAgreementNumber() {
        return agreementNumber;
      }

      public BigInteger getDebtAmount() {
        return debtAmount;
      }
    }
    class ExternalDebt implements Result {
      private final String debtSource;
      private final BigInteger debtAmount;

      public ExternalDebt(String debtSource, BigInteger debtAmount) {
        this.debtSource = debtSource;
        this.debtAmount = debtAmount;
      }

      public String getDebtSource() {
        return debtSource;
      }

      public BigInteger getDebtAmount() {
        return debtAmount;
      }
    }
    class PositiveDecision implements Result {
      private final BigInteger maxAmount;

      public PositiveDecision(BigInteger maxAmount) {
        this.maxAmount = maxAmount;
      }

      public BigInteger getMaxAmount() {
        return maxAmount;
      }
    }
  }
}

Comparing to Scala example there still is much more code lines. But the main advantage of this approach is better encapsulation. You don't create separated file for every interface and class. Especially since they don't make sense outside the context of CustomerVerificationService class. Pay also attention I changed name of VerificationResult interface to Result. Due to the fact Result is part of CustomerVerificationService class, its name may be less precise.

But still, if code volume bother you, Java14 comes to the rescue. More specifically Java 14 introduces record keyword which is closer to Scala class even than Java class. With Java record you can reduce earlier implementation of BlackListedCustomer to one line:

record BlackListedCustomer(String reason) implements Result { }

The Java compiler auto generates getter methods, toString(), hashcode() and equals() methods, so you don't have to write that boilerplate code yourself. Since a Java record is immutable, no setter methods are generated. Final version (in Java 14) may look like:

public class CustomerVerificationService {

  public  Result verifyPaymentHistory(Customer customer) {
    //omitted code
    return new Results.PositiveDecision(BigInteger.valueOf(6000L));
  }

  public static record Customer(String pesel, String firstName, String lastName, String idNumber) { }
  public interface Result { }
  public interface Results {
    record BlackListedCustomer(String reason) implements Result { }
    record InternalDebt(String agreementNumber, BigInteger debtAmount) implements Result { }
    record ExternalDebt(String debtSource, BigInteger debtAmount) implements Result { }
    record PositiveDecision(BigInteger maxAmount) implements Result { }
  }
}

Look how above implementation is similar to the Scala example.

In this post I wanted to show how nicely and easy you can encapsulate your code using inner static classes, enums and interfaces. Pay also attention how Java evolution made it simpler. Java 14 record keyword hiding boilerplate code and lets you focus on implementation.

Originally published at https://stepniewski.tech.

All Java examples from this post you will find at my github.