├── .github └── workflows │ └── build.yml ├── .gitignore ├── CONTRIBUTING.md ├── LICENSE.md ├── NOTICE.md ├── README.md ├── pom.xml ├── src └── main │ ├── asciidoc │ ├── batch-processing │ │ ├── batch-processing.adoc │ │ ├── batch-processing001.adoc │ │ ├── batch-processing002.adoc │ │ ├── batch-processing003.adoc │ │ ├── batch-processing004.adoc │ │ ├── batch-processing005.adoc │ │ ├── batch-processing006.adoc │ │ ├── batch-processing007.adoc │ │ ├── batch-processing008.adoc │ │ ├── batch-processing009.adoc │ │ └── batch-processing010.adoc │ ├── bean-validation-advanced │ │ ├── bean-validation-advanced.adoc │ │ ├── bean-validation-advanced001.adoc │ │ ├── bean-validation-advanced002.adoc │ │ ├── bean-validation-advanced003.adoc │ │ └── bean-validation-advanced004.adoc │ ├── bean-validation │ │ ├── bean-validation.adoc │ │ ├── bean-validation001.adoc │ │ ├── bean-validation002.adoc │ │ ├── bean-validation003.adoc │ │ ├── bean-validation004.adoc │ │ └── bean-validation005.adoc │ ├── cdi-adv-examples │ │ ├── cdi-adv-examples.adoc │ │ ├── cdi-adv-examples001.adoc │ │ ├── cdi-adv-examples002.adoc │ │ ├── cdi-adv-examples003.adoc │ │ ├── cdi-adv-examples004.adoc │ │ ├── cdi-adv-examples005.adoc │ │ └── cdi-adv-examples006.adoc │ ├── cdi-adv │ │ ├── cdi-adv.adoc │ │ ├── cdi-adv001.adoc │ │ ├── cdi-adv002.adoc │ │ ├── cdi-adv003.adoc │ │ ├── cdi-adv004.adoc │ │ ├── cdi-adv005.adoc │ │ ├── cdi-adv006.adoc │ │ ├── cdi-adv007.adoc │ │ ├── cdi-adv008.adoc │ │ ├── cdi-adv009.adoc │ │ └── cdi-adv010.adoc │ ├── cdi-basic │ │ ├── cdi-basic.adoc │ │ ├── cdi-basic001.adoc │ │ ├── cdi-basic002.adoc │ │ ├── cdi-basic003.adoc │ │ ├── cdi-basic004.adoc │ │ ├── cdi-basic005.adoc │ │ ├── cdi-basic006.adoc │ │ ├── cdi-basic007.adoc │ │ ├── cdi-basic008.adoc │ │ ├── cdi-basic009.adoc │ │ ├── cdi-basic010.adoc │ │ ├── cdi-basic011.adoc │ │ ├── cdi-basic012.adoc │ │ ├── cdi-basic013.adoc │ │ ├── cdi-basic014.adoc │ │ └── cdi-basic015.adoc │ ├── cdi-basicexamples │ │ ├── cdi-basicexamples.adoc │ │ ├── cdi-basicexamples001.adoc │ │ ├── cdi-basicexamples002.adoc │ │ └── cdi-basicexamples003.adoc │ ├── cdi-bootstrap-se8 │ │ ├── cdi-bootstrap-se8.adoc │ │ ├── cdi-bootstrap-se8001.adoc │ │ └── cdi-bootstrap-se8002.adoc │ ├── concurrency-utilities │ │ ├── concurrency-utilities.adoc │ │ ├── concurrency-utilities001.adoc │ │ ├── concurrency-utilities002.adoc │ │ ├── concurrency-utilities003.adoc │ │ ├── concurrency-utilities004.adoc │ │ ├── concurrency-utilities005.adoc │ │ ├── concurrency-utilities006.adoc │ │ └── concurrency-utilities007.adoc │ ├── connectorexample │ │ ├── connectorexample.adoc │ │ ├── connectorexample001.adoc │ │ ├── connectorexample002.adoc │ │ └── connectorexample003.adoc │ ├── dukes-bookstore │ │ ├── dukes-bookstore.adoc │ │ ├── dukes-bookstore001.adoc │ │ ├── dukes-bookstore002.adoc │ │ └── dukes-bookstore003.adoc │ ├── dukes-forest │ │ ├── dukes-forest.adoc │ │ ├── dukes-forest001.adoc │ │ ├── dukes-forest002.adoc │ │ ├── dukes-forest003.adoc │ │ └── dukes-forest004.adoc │ ├── dukes-tutoring │ │ ├── dukes-tutoring.adoc │ │ ├── dukes-tutoring001.adoc │ │ ├── dukes-tutoring002.adoc │ │ ├── dukes-tutoring003.adoc │ │ └── dukes-tutoring004.adoc │ ├── ejb-async │ │ ├── ejb-async.adoc │ │ ├── ejb-async001.adoc │ │ └── ejb-async002.adoc │ ├── ejb-basicexamples │ │ ├── ejb-basicexamples.adoc │ │ ├── ejb-basicexamples001.adoc │ │ ├── ejb-basicexamples002.adoc │ │ ├── ejb-basicexamples003.adoc │ │ ├── ejb-basicexamples004.adoc │ │ ├── ejb-basicexamples005.adoc │ │ └── ejb-basicexamples006.adoc │ ├── ejb-embedded │ │ ├── ejb-embedded.adoc │ │ ├── ejb-embedded001.adoc │ │ ├── ejb-embedded002.adoc │ │ └── ejb-embedded003.adoc │ ├── ejb-gettingstarted │ │ ├── ejb-gettingstarted.adoc │ │ ├── ejb-gettingstarted001.adoc │ │ ├── ejb-gettingstarted002.adoc │ │ └── ejb-gettingstarted003.adoc │ ├── ejb-intro │ │ ├── ejb-intro.adoc │ │ ├── ejb-intro001.adoc │ │ ├── ejb-intro002.adoc │ │ ├── ejb-intro003.adoc │ │ ├── ejb-intro004.adoc │ │ ├── ejb-intro005.adoc │ │ ├── ejb-intro006.adoc │ │ ├── ejb-intro007.adoc │ │ └── ejb-intro008.adoc │ ├── faces-advanced-cc │ │ ├── faces-advanced-cc.adoc │ │ ├── faces-advanced-cc001.adoc │ │ ├── faces-advanced-cc002.adoc │ │ ├── faces-advanced-cc003.adoc │ │ └── faces-advanced-cc004.adoc │ ├── faces-ajax │ │ ├── faces-ajax.adoc │ │ ├── faces-ajax001.adoc │ │ ├── faces-ajax002.adoc │ │ ├── faces-ajax003.adoc │ │ ├── faces-ajax004.adoc │ │ ├── faces-ajax005.adoc │ │ ├── faces-ajax006.adoc │ │ ├── faces-ajax007.adoc │ │ ├── faces-ajax008.adoc │ │ ├── faces-ajax009.adoc │ │ ├── faces-ajax010.adoc │ │ ├── faces-ajax011.adoc │ │ └── faces-ajax012.adoc │ ├── faces-configure │ │ ├── faces-configure.adoc │ │ ├── faces-configure001.adoc │ │ ├── faces-configure002.adoc │ │ ├── faces-configure003.adoc │ │ ├── faces-configure004.adoc │ │ ├── faces-configure006.adoc │ │ ├── faces-configure007.adoc │ │ ├── faces-configure008.adoc │ │ ├── faces-configure009.adoc │ │ ├── faces-configure010.adoc │ │ ├── faces-configure011.adoc │ │ ├── faces-configure012.adoc │ │ └── faces-configure013.adoc │ ├── faces-custom │ │ ├── faces-custom.adoc │ │ ├── faces-custom001.adoc │ │ ├── faces-custom002.adoc │ │ ├── faces-custom003.adoc │ │ ├── faces-custom004.adoc │ │ ├── faces-custom005.adoc │ │ ├── faces-custom006.adoc │ │ ├── faces-custom007.adoc │ │ ├── faces-custom008.adoc │ │ ├── faces-custom009.adoc │ │ ├── faces-custom010.adoc │ │ ├── faces-custom011.adoc │ │ ├── faces-custom012.adoc │ │ ├── faces-custom013.adoc │ │ └── faces-custom014.adoc │ ├── faces-develop │ │ ├── faces-develop.adoc │ │ ├── faces-develop001.adoc │ │ ├── faces-develop002.adoc │ │ └── faces-develop003.adoc │ ├── faces-el │ │ ├── faces-el.adoc │ │ ├── faces-el001.adoc │ │ ├── faces-el002.adoc │ │ ├── faces-el003.adoc │ │ ├── faces-el004.adoc │ │ ├── faces-el005.adoc │ │ ├── faces-el006.adoc │ │ ├── faces-el007.adoc │ │ └── faces-el008.adoc │ ├── faces-facelets │ │ ├── faces-facelets.adoc │ │ ├── faces-facelets001.adoc │ │ ├── faces-facelets002.adoc │ │ ├── faces-facelets003.adoc │ │ ├── faces-facelets004.adoc │ │ ├── faces-facelets005.adoc │ │ ├── faces-facelets006.adoc │ │ ├── faces-facelets007.adoc │ │ ├── faces-facelets008.adoc │ │ └── faces-facelets009.adoc │ ├── faces-intro │ │ ├── faces-intro.adoc │ │ ├── faces-intro001.adoc │ │ ├── faces-intro002.adoc │ │ ├── faces-intro003.adoc │ │ ├── faces-intro004.adoc │ │ ├── faces-intro005.adoc │ │ ├── faces-intro006.adoc │ │ ├── faces-intro007.adoc │ │ ├── faces-intro008.adoc │ │ └── faces-intro009.adoc │ ├── faces-page-core │ │ ├── faces-page-core.adoc │ │ ├── faces-page-core001.adoc │ │ ├── faces-page-core002.adoc │ │ ├── faces-page-core003.adoc │ │ └── faces-page-core004.adoc │ ├── faces-page │ │ ├── faces-page.adoc │ │ ├── faces-page001.adoc │ │ ├── faces-page002.adoc │ │ └── faces-page003.adoc │ ├── faces-ws │ │ ├── faces-ws.adoc │ │ ├── faces-ws001.adoc │ │ ├── faces-ws002.adoc │ │ ├── faces-ws003.adoc │ │ ├── faces-ws004.adoc │ │ ├── faces-ws005.adoc │ │ ├── faces-ws006.adoc │ │ └── faces-ws007.adoc │ ├── images │ │ ├── eclipse_foundation_logo_tiny.png │ │ ├── jakartaeett_dt_001.svg │ │ ├── jakartaeett_dt_002.svg │ │ ├── jakartaeett_dt_003.svg │ │ ├── jakartaeett_dt_004.svg │ │ ├── jakartaeett_dt_005.svg │ │ ├── jakartaeett_dt_006.svg │ │ ├── jakartaeett_dt_007.svg │ │ ├── jakartaeett_dt_008.svg │ │ ├── jakartaeett_dt_009.svg │ │ ├── jakartaeett_dt_010.svg │ │ ├── jakartaeett_dt_011.svg │ │ ├── jakartaeett_dt_012.svg │ │ ├── jakartaeett_dt_013.svg │ │ ├── jakartaeett_dt_014.svg │ │ ├── jakartaeett_dt_015.svg │ │ ├── jakartaeett_dt_016.svg │ │ ├── jakartaeett_dt_017.svg │ │ ├── jakartaeett_dt_018.svg │ │ ├── jakartaeett_dt_019.svg │ │ ├── jakartaeett_dt_020.svg │ │ ├── jakartaeett_dt_021.svg │ │ ├── jakartaeett_dt_022.svg │ │ ├── jakartaeett_dt_023.svg │ │ ├── jakartaeett_dt_024.svg │ │ ├── jakartaeett_dt_025.svg │ │ ├── jakartaeett_dt_026.svg │ │ ├── jakartaeett_dt_027.svg │ │ ├── jakartaeett_dt_028.svg │ │ ├── jakartaeett_dt_029.svg │ │ ├── jakartaeett_dt_030.svg │ │ ├── jakartaeett_dt_031.svg │ │ ├── jakartaeett_dt_032.svg │ │ ├── jakartaeett_dt_033.svg │ │ ├── jakartaeett_dt_034.svg │ │ ├── jakartaeett_dt_035.svg │ │ ├── jakartaeett_dt_036.svg │ │ ├── jakartaeett_dt_037.svg │ │ ├── jakartaeett_dt_038.svg │ │ ├── jakartaeett_dt_039.svg │ │ ├── jakartaeett_dt_040.svg │ │ ├── jakartaeett_dt_041.svg │ │ ├── jakartaeett_dt_042.svg │ │ ├── jakartaeett_dt_043.svg │ │ ├── jakartaeett_dt_044.svg │ │ ├── jakartaeett_dt_045.svg │ │ ├── jakartaeett_dt_046.svg │ │ ├── jakartaeett_dt_047.svg │ │ ├── jakartaeett_dt_048.svg │ │ ├── jakartaeett_dt_049.svg │ │ ├── jakartaeett_dt_050.svg │ │ ├── jakartaeett_dt_051.svg │ │ ├── jakartaeett_dt_052.svg │ │ ├── jakartaeett_dt_053.svg │ │ ├── jakartaeett_dt_054.svg │ │ ├── jakartaeett_dt_055.svg │ │ ├── jakartaeett_dt_056.svg │ │ ├── jakartaeett_dt_057.svg │ │ ├── jakartaeett_dt_058.svg │ │ ├── jakartaeett_dt_059.svg │ │ ├── jakartaeett_dt_060.svg │ │ ├── jakartaeett_dt_061.svg │ │ ├── jakartaeett_dt_062.svg │ │ ├── jakartaeett_dt_063.svg │ │ ├── jakartaeett_dt_064.svg │ │ ├── jakartaeett_dt_065_frmcmpnt.svg │ │ ├── jakartaeett_dt_066_slctmny.svg │ │ ├── jakartaeett_dt_067_slctn.svg │ │ └── jakartaeett_dt_068_txtcmpnts.svg │ ├── index.adoc │ ├── injection │ │ ├── injection.adoc │ │ ├── injection001.adoc │ │ ├── injection002.adoc │ │ └── injection003.adoc │ ├── interceptors │ │ ├── interceptors.adoc │ │ ├── interceptors001.adoc │ │ ├── interceptors002.adoc │ │ └── interceptors003.adoc │ ├── jaxrs-advanced │ │ ├── jaxrs-advanced.adoc │ │ ├── jaxrs-advanced001.adoc │ │ ├── jaxrs-advanced002.adoc │ │ ├── jaxrs-advanced003.adoc │ │ ├── jaxrs-advanced004.adoc │ │ ├── jaxrs-advanced005.adoc │ │ ├── jaxrs-advanced006.adoc │ │ ├── jaxrs-advanced007.adoc │ │ └── jaxrs-advanced008.adoc │ ├── jaxrs-client │ │ ├── jaxrs-client.adoc │ │ ├── jaxrs-client001.adoc │ │ ├── jaxrs-client002.adoc │ │ └── jaxrs-client003.adoc │ ├── jaxrs │ │ ├── jaxrs.adoc │ │ ├── jaxrs001.adoc │ │ ├── jaxrs002.adoc │ │ ├── jaxrs003.adoc │ │ └── jaxrs004.adoc │ ├── jaxws │ │ ├── jaxws.adoc │ │ ├── jaxws001.adoc │ │ ├── jaxws002.adoc │ │ ├── jaxws003.adoc │ │ ├── jaxws004.adoc │ │ └── jaxws005.adoc │ ├── jms-concepts │ │ ├── jms-concepts.adoc │ │ ├── jms-concepts001.adoc │ │ ├── jms-concepts002.adoc │ │ ├── jms-concepts003.adoc │ │ ├── jms-concepts004.adoc │ │ ├── jms-concepts005.adoc │ │ └── jms-concepts006.adoc │ ├── jms-examples │ │ ├── jms-examples.adoc │ │ ├── jms-examples001.adoc │ │ ├── jms-examples002.adoc │ │ ├── jms-examples003.adoc │ │ ├── jms-examples004.adoc │ │ ├── jms-examples005.adoc │ │ ├── jms-examples006.adoc │ │ ├── jms-examples007.adoc │ │ ├── jms-examples008.adoc │ │ ├── jms-examples009.adoc │ │ └── jms-examples010.adoc │ ├── jsonb │ │ ├── jsonb.adoc │ │ ├── jsonb001.adoc │ │ ├── jsonb002.adoc │ │ ├── jsonb003.adoc │ │ └── jsonb004.adoc │ ├── jsonp │ │ ├── jsonp.adoc │ │ ├── jsonp001.adoc │ │ ├── jsonp002.adoc │ │ ├── jsonp003.adoc │ │ ├── jsonp004.adoc │ │ ├── jsonp005.adoc │ │ ├── jsonp006.adoc │ │ ├── jsonp007.adoc │ │ └── jsonp008.adoc │ ├── overview │ │ ├── overview.adoc │ │ ├── overview001.adoc │ │ ├── overview002.adoc │ │ ├── overview003.adoc │ │ ├── overview004.adoc │ │ ├── overview005.adoc │ │ ├── overview006.adoc │ │ ├── overview007.adoc │ │ ├── overview008.adoc │ │ ├── overview009.adoc │ │ └── overview010.adoc │ ├── packaging │ │ ├── packaging.adoc │ │ ├── packaging001.adoc │ │ ├── packaging002.adoc │ │ ├── packaging003.adoc │ │ └── packaging004.adoc │ ├── partbeanvalidation.adoc │ ├── partcasestudies.adoc │ ├── partcdi.adoc │ ├── partentbeans.adoc │ ├── partintro.adoc │ ├── partmessaging.adoc │ ├── partpersist.adoc │ ├── partplatform.adoc │ ├── partsecurity.adoc │ ├── partsupporttechs.adoc │ ├── partwebsvcs.adoc │ ├── partwebtier.adoc │ ├── persistence-basicexamples │ │ ├── persistence-basicexamples.adoc │ │ ├── persistence-basicexamples001.adoc │ │ ├── persistence-basicexamples002.adoc │ │ ├── persistence-basicexamples003.adoc │ │ └── persistence-basicexamples004.adoc │ ├── persistence-cache │ │ ├── persistence-cache.adoc │ │ ├── persistence-cache001.adoc │ │ └── persistence-cache002.adoc │ ├── persistence-criteria │ │ ├── persistence-criteria.adoc │ │ ├── persistence-criteria001.adoc │ │ ├── persistence-criteria002.adoc │ │ └── persistence-criteria003.adoc │ ├── persistence-entitygraphs │ │ ├── persistence-entitygraphs.adoc │ │ ├── persistence-entitygraphs001.adoc │ │ ├── persistence-entitygraphs002.adoc │ │ ├── persistence-entitygraphs003.adoc │ │ └── persistence-entitygraphs004.adoc │ ├── persistence-intro │ │ ├── persistence-intro.adoc │ │ ├── persistence-intro001.adoc │ │ ├── persistence-intro002.adoc │ │ ├── persistence-intro003.adoc │ │ ├── persistence-intro004.adoc │ │ ├── persistence-intro005.adoc │ │ ├── persistence-intro006.adoc │ │ └── persistence-intro007.adoc │ ├── persistence-locking │ │ ├── persistence-locking.adoc │ │ ├── persistence-locking001.adoc │ │ └── persistence-locking002.adoc │ ├── persistence-querylanguage │ │ ├── persistence-querylanguage.adoc │ │ ├── persistence-querylanguage001.adoc │ │ ├── persistence-querylanguage002.adoc │ │ ├── persistence-querylanguage003.adoc │ │ ├── persistence-querylanguage004.adoc │ │ ├── persistence-querylanguage005.adoc │ │ └── persistence-querylanguage006.adoc │ ├── persistence-string-queries │ │ ├── persistence-string-queries.adoc │ │ ├── persistence-string-queries001.adoc │ │ ├── persistence-string-queries002.adoc │ │ └── persistence-string-queries003.adoc │ ├── preface.adoc │ ├── resource-creation │ │ ├── resource-creation.adoc │ │ ├── resource-creation001.adoc │ │ ├── resource-creation002.adoc │ │ └── resource-creation003.adoc │ ├── resources │ │ ├── resources.adoc │ │ ├── resources001.adoc │ │ ├── resources002.adoc │ │ ├── resources003.adoc │ │ ├── resources004.adoc │ │ └── resources005.adoc │ ├── security-advanced │ │ ├── security-advanced.adoc │ │ ├── security-advanced001.adoc │ │ ├── security-advanced002.adoc │ │ ├── security-advanced003.adoc │ │ ├── security-advanced004.adoc │ │ ├── security-advanced005.adoc │ │ ├── security-advanced006.adoc │ │ ├── security-advanced007.adoc │ │ └── security-advanced008.adoc │ ├── security-api │ │ ├── security-api.adoc │ │ ├── security-api001.adoc │ │ ├── security-api002.adoc │ │ ├── security-api003.adoc │ │ ├── security-api004.adoc │ │ └── security-api005.adoc │ ├── security-intro │ │ ├── security-intro.adoc │ │ ├── security-intro001.adoc │ │ ├── security-intro002.adoc │ │ ├── security-intro003.adoc │ │ ├── security-intro003a.adoc │ │ ├── security-intro004.adoc │ │ ├── security-intro005.adoc │ │ ├── security-intro005a.adoc │ │ ├── security-intro006.adoc │ │ └── security-intro007.adoc │ ├── security-jakartaee │ │ ├── security-jakartaee.adoc │ │ ├── security-jakartaee001.adoc │ │ ├── security-jakartaee002.adoc │ │ └── security-jakartaee003.adoc │ ├── security-webtier │ │ ├── security-webtier.adoc │ │ ├── security-webtier001.adoc │ │ ├── security-webtier002.adoc │ │ ├── security-webtier003.adoc │ │ └── security-webtier004.adoc │ ├── servlets │ │ ├── servlets.adoc │ │ ├── servlets001.adoc │ │ ├── servlets002.adoc │ │ ├── servlets003.adoc │ │ ├── servlets004.adoc │ │ ├── servlets005.adoc │ │ ├── servlets006.adoc │ │ ├── servlets007.adoc │ │ ├── servlets008.adoc │ │ ├── servlets009.adoc │ │ ├── servlets010.adoc │ │ ├── servlets011.adoc │ │ ├── servlets012.adoc │ │ ├── servlets013.adoc │ │ ├── servlets014.adoc │ │ ├── servlets014a.adoc │ │ ├── servlets014b.adoc │ │ ├── servlets015.adoc │ │ ├── servlets016.adoc │ │ ├── servlets017.adoc │ │ └── servlets018.adoc │ ├── title.adoc │ ├── transactions │ │ ├── transactions.adoc │ │ ├── transactions001.adoc │ │ ├── transactions002.adoc │ │ ├── transactions003.adoc │ │ ├── transactions004.adoc │ │ ├── transactions005.adoc │ │ ├── transactions006.adoc │ │ ├── transactions007.adoc │ │ ├── transactions008.adoc │ │ └── transactions009.adoc │ ├── usingexamples │ │ ├── usingexamples.adoc │ │ ├── usingexamples001.adoc │ │ ├── usingexamples002.adoc │ │ ├── usingexamples003.adoc │ │ ├── usingexamples004.adoc │ │ ├── usingexamples005.adoc │ │ ├── usingexamples006.adoc │ │ ├── usingexamples007.adoc │ │ ├── usingexamples008.adoc │ │ └── usingexamples009.adoc │ ├── webapp │ │ ├── webapp.adoc │ │ ├── webapp001.adoc │ │ ├── webapp002.adoc │ │ ├── webapp003.adoc │ │ ├── webapp004.adoc │ │ ├── webapp005.adoc │ │ └── webapp006.adoc │ ├── webi18n │ │ ├── webi18n.adoc │ │ ├── webi18n001.adoc │ │ ├── webi18n002.adoc │ │ ├── webi18n003.adoc │ │ └── webi18n004.adoc │ ├── webservices-intro │ │ ├── webservices-intro.adoc │ │ ├── webservices-intro001.adoc │ │ ├── webservices-intro002.adoc │ │ └── webservices-intro003.adoc │ └── websocket │ │ ├── websocket.adoc │ │ ├── websocket001.adoc │ │ ├── websocket002.adoc │ │ ├── websocket003.adoc │ │ ├── websocket004.adoc │ │ ├── websocket005.adoc │ │ ├── websocket006.adoc │ │ ├── websocket007.adoc │ │ ├── websocket008.adoc │ │ ├── websocket009.adoc │ │ ├── websocket010.adoc │ │ ├── websocket011.adoc │ │ ├── websocket012.adoc │ │ └── websocket013.adoc │ ├── jbake │ └── assets │ │ └── img │ │ └── icons │ │ └── computer.svg │ └── ruby │ └── autoxref-treeprocessor.rb └── tutorial.xml /.github/workflows/build.yml: -------------------------------------------------------------------------------- 1 | name: build 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | - release/* 8 | pull_request: 9 | branches: 10 | - master 11 | 12 | jobs: 13 | 14 | build: 15 | runs-on: ubuntu-latest 16 | steps: 17 | 18 | - uses: actions/checkout@v1 19 | 20 | - name: Set up JDK 1.8 21 | uses: actions/setup-java@v1 22 | with: 23 | java-version: 1.8 24 | 25 | - name: Build Docs 26 | run: mvn clean package --file pom.xml #-Ppublish-site 27 | 28 | # - name: Deploy 🚀 29 | # uses: JamesIves/github-pages-deploy-action@3.7.1 30 | # with: 31 | # GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 32 | # BRANCH: gh-pages # The branch the action should deploy to. 33 | # FOLDER: target/generated-docs # The folder the action should deploy. 34 | # CLEAN: true # Automatically remove deleted files from the deploy br 35 | 36 | 37 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | target/ 2 | src/main/jbake/content/toc.adoc 3 | 4 | # Eclipse # 5 | .settings/ 6 | *.classpath 7 | *.project 8 | 9 | # IntelliJ # 10 | .idea/ 11 | *.iml 12 | 13 | # OS Files # 14 | .DS_Store -------------------------------------------------------------------------------- /NOTICE.md: -------------------------------------------------------------------------------- 1 | # Notices for Jakarta EE Platform 2 | 3 | This content is produced and maintained by the Jakarta EE Platform 4 | project. 5 | 6 | * Project home: https://projects.eclipse.org/projects/ee4j.jakartaee-platform 7 | 8 | ## Trademarks 9 | 10 | Jakarta EE Platform is a trademark of the Eclipse Foundation. 11 | 12 | ## Copyright 13 | 14 | All content is the property of the respective authors or their employers. For 15 | more information regarding authorship of content, please consult the listed 16 | source code repository logs. 17 | 18 | ## Declared Project Licenses 19 | 20 | This program and the accompanying materials are made available under the terms 21 | of the Eclipse Public License v. 2.0 which is available at 22 | http://www.eclipse.org/legal/epl-2.0. 23 | 24 | SPDX-License-Identifier: EPL-2.0 25 | 26 | ## Source Code 27 | 28 | The project maintains the following source code repositories: 29 | 30 | * https://github.com/eclipse-ee4j/jakartaee-platform 31 | * https://github.com/eclipse-ee4j/jakartaee-tutorial 32 | * https://github.com/eclipse-ee4j/jakartaee-tutorial-examples 33 | * https://github.com/eclipse-ee4j/jakartaee-firstcup 34 | * https://github.com/eclipse-ee4j/jakartaee-firstcup-examples 35 | * https://github.com/eclipse-ee4j/jakartaee-schemas 36 | 37 | ## Third-party Content 38 | 39 | This project leverages the following third party content. 40 | 41 | W3C Documents for JakartaEE Schemas (n/a) 42 | 43 | * License: W3C-19980720 44 | * Project: https://github.com/eclipse-ee4j/jakartaee-schemas 45 | * Source: http://www.w3.org/2001 46 | 47 | ## Cryptography 48 | 49 | Content may contain encryption software. The country in which you are currently 50 | may have restrictions on the import, possession, and use, and/or re-export to 51 | another country, of encryption software. BEFORE using any encryption software, 52 | please check the country's laws, regulations and policies concerning the import, 53 | possession, or use, and re-export of encryption software, to see if this is 54 | permitted. 55 | -------------------------------------------------------------------------------- /src/main/asciidoc/batch-processing/batch-processing.adoc: -------------------------------------------------------------------------------- 1 | = Batch Processing 2 | 3 | This chapter describes Jakarta Batch, which provides support for defining, implementing, and running batch jobs. 4 | Batch jobs are tasks that can be executed without user interaction. 5 | The batch framework is composed of a job specification language based on XML, a Java API, and a batch runtime. 6 | 7 | include::batch-processing001.adoc[] 8 | 9 | include::batch-processing002.adoc[] 10 | 11 | include::batch-processing003.adoc[] 12 | 13 | include::batch-processing004.adoc[] 14 | 15 | include::batch-processing005.adoc[] 16 | 17 | include::batch-processing006.adoc[] 18 | 19 | include::batch-processing007.adoc[] 20 | 21 | include::batch-processing008.adoc[] 22 | 23 | include::batch-processing009.adoc[] 24 | 25 | include::batch-processing010.adoc[] 26 | -------------------------------------------------------------------------------- /src/main/asciidoc/batch-processing/batch-processing007.adoc: -------------------------------------------------------------------------------- 1 | == Packaging Batch Applications 2 | 3 | Job definition files and batch artifacts do not require separate packaging and can be included in any Jakarta EE application. 4 | 5 | Package the batch artifact classes with the rest of the classes of your application, and include the job definition files in one of the following directories: 6 | 7 | * `META-INF/batch-jobs/` for `jar` packages 8 | 9 | * `WEB-INF/classes/META-INF/batch-jobs/` for `war` packages 10 | 11 | The name of each job definition file must match its job ID. 12 | For example, if you define a job as follows, and you are packaging your application as a WAR file, include the job definition file in `WEB-INF/classes/META-INF/batch-jobs/simplejob.xml`: 13 | 14 | [source,xml] 15 | ---- 16 | 18 | ... 19 | 20 | ---- 21 | -------------------------------------------------------------------------------- /src/main/asciidoc/batch-processing/batch-processing010.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Batch Processing 2 | 3 | For more information on batch processing in Jakarta EE, see Jakarta Batch: + 4 | https://jakarta.ee/specifications/batch/2.0/[^] 5 | -------------------------------------------------------------------------------- /src/main/asciidoc/bean-validation-advanced/bean-validation-advanced.adoc: -------------------------------------------------------------------------------- 1 | = Bean Validation: Advanced Topics 2 | 3 | This chapter describes how to create custom constraints, custom validator messages, and constraint groups using the Jakarta Bean Validation (Bean Validation). 4 | 5 | include::bean-validation-advanced001.adoc[] 6 | 7 | include::bean-validation-advanced002.adoc[] 8 | 9 | include::bean-validation-advanced003.adoc[] 10 | 11 | include::bean-validation-advanced004.adoc[] 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/bean-validation-advanced/bean-validation-advanced002.adoc: -------------------------------------------------------------------------------- 1 | == Customizing Validator Messages 2 | 3 | Jakarta Bean Validation includes a resource bundle of default messages for the built-in constraints. 4 | These messages can be customized and can be localized for non-English-speaking locales. 5 | 6 | === The ValidationMessages Resource Bundle 7 | 8 | The `ValidationMessages` resource bundle and the locale variants of this resource bundle contain strings that override the default validation messages. 9 | The `ValidationMessages` resource bundle is typically a properties file, `ValidationMessages.properties`, in the default package of an application. 10 | 11 | ==== Localizing Validation Messages 12 | 13 | Locale variants of `ValidationMessages.properties` are added by appending an underscore and the locale prefix to the base name of the file. 14 | For example, the Spanish locale variant resource bundle would be `ValidationMessages_es.properties`. 15 | -------------------------------------------------------------------------------- /src/main/asciidoc/bean-validation/bean-validation.adoc: -------------------------------------------------------------------------------- 1 | = Introduction to Jakarta Bean Validation 2 | 3 | This chapter describes Jakarta Bean Validation available as part of the Jakarta EE platform and the facility for validating objects, object members, methods, and constructors. 4 | 5 | include::bean-validation001.adoc[] 6 | 7 | include::bean-validation002.adoc[] 8 | 9 | include::bean-validation003.adoc[] 10 | 11 | include::bean-validation004.adoc[] 12 | 13 | include::bean-validation005.adoc[] 14 | -------------------------------------------------------------------------------- /src/main/asciidoc/bean-validation/bean-validation001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of Jakarta Bean Validation 2 | 3 | Validating input received from the user to maintain data integrity is an important part of application logic. 4 | Validation of data can take place at different layers in even the simplest of applications, as shown in <>. 5 | The `guessnumber-faces` example application validates the user input (in the `h:inputText` tag) for numerical data at the presentation layer and for a valid range of numbers at the business layer. 6 | 7 | Jakarta Bean Validation provides a facility for validating objects, object members, methods, and constructors. 8 | In Jakarta EE environments, Jakarta Bean Validation integrates with Jakarta EE containers and services to allow developers to easily define and enforce validation constraints. 9 | Jakarta Bean Validation is available as part of the Jakarta EE platform. 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/bean-validation/bean-validation005.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Jakarta Bean Validation 2 | 3 | For more information on Jakarta Bean Validation, see 4 | 5 | * Jakarta Bean Validation 3.0 Specification: + 6 | https://jakarta.ee/specifications/bean-validation/3.0/[^] 7 | 8 | * Bean Validation Specification website: + 9 | https://beanvalidation.org/[^] 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-adv-examples/cdi-adv-examples.adoc: -------------------------------------------------------------------------------- 1 | = Running the Advanced Contexts and Dependency Injection Examples 2 | 3 | This chapter describes in detail how to build and run several advanced examples that use CDI. 4 | 5 | include::cdi-adv-examples001.adoc[] 6 | 7 | include::cdi-adv-examples002.adoc[] 8 | 9 | include::cdi-adv-examples003.adoc[] 10 | 11 | include::cdi-adv-examples004.adoc[] 12 | 13 | include::cdi-adv-examples005.adoc[] 14 | 15 | include::cdi-adv-examples006.adoc[] 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-adv-examples/cdi-adv-examples001.adoc: -------------------------------------------------------------------------------- 1 | == Building and Running the CDI Advanced Examples 2 | 3 | The examples are in the `_tut-install_/examples/cdi/` directory. 4 | To build and run the examples, you will do the following. 5 | 6 | . Use NetBeans IDE or the Maven tool to compile, package, and deploy the example. 7 | 8 | . Run the example in a web browser. 9 | 10 | See xref:using-the-tutorial-examples[xrefstyle=full], for basic information on installing, building, and running the examples. 11 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-adv/cdi-adv.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta Contexts and Dependency Injection: Advanced Topics 2 | 3 | This chapter describes more advanced features of Jakarta Contexts and Dependency Injection. 4 | Specifically, it covers additional features CDI provides to enable loose coupling of components with strong typing, in addition to those described in <>. 5 | 6 | include::cdi-adv001.adoc[] 7 | 8 | include::cdi-adv002.adoc[] 9 | 10 | include::cdi-adv003.adoc[] 11 | 12 | include::cdi-adv004.adoc[] 13 | 14 | include::cdi-adv005.adoc[] 15 | 16 | include::cdi-adv006.adoc[] 17 | 18 | include::cdi-adv007.adoc[] 19 | 20 | include::cdi-adv008.adoc[] 21 | 22 | include::cdi-adv009.adoc[] 23 | 24 | include::cdi-adv010.adoc[] 25 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-adv/cdi-adv001.adoc: -------------------------------------------------------------------------------- 1 | == Packaging CDI Applications 2 | 3 | When you deploy a Jakarta EE application, CDI looks for beans inside bean archives. 4 | A bean archive is any module that contains beans that the CDI runtime can manage and inject. 5 | There are two kinds of bean archives: explicit bean archives and implicit bean archives. 6 | 7 | An explicit bean archive is an archive that contains a `beans.xml` deployment descriptor, which can be an empty file, contain no version number, or contain the version number 3.0 with the `bean-discovery-mode` attribute set to `all`. 8 | For example: 9 | 10 | [source,xml] 11 | ---- 12 | 13 | 18 | ... 19 | 20 | ---- 21 | 22 | CDI can manage and inject any bean in an explicit archive, except those annotated with `@Vetoed`. 23 | 24 | An implicit bean archive is an archive that contains some beans annotated with a scope type, contains no `beans.xml` deployment descriptor, or contains a `beans.xml` deployment descriptor with the `bean-discovery-mode` attribute set to `annotated`. 25 | 26 | In an implicit archive, CDI can only manage and inject beans annotated with a scope type. 27 | 28 | For a web application, the `beans.xml` deployment descriptor, if present, must be in the `WEB-INF` directory. 29 | For enterprise bean modules or JAR files, the `beans.xml` deployment descriptor, if present, must be in the `META-INF` directory. 30 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-adv/cdi-adv009.adoc: -------------------------------------------------------------------------------- 1 | == Using the Built-In Annotation Literals 2 | 3 | The following built-in annotations define a `Literal` static nested class, which can be used as a convenience feature for creating instances of annotations: 4 | 5 | * `jakarta.enterprise.inject.Any` 6 | 7 | * `jakarta.enterprise.inject.Default` 8 | 9 | * `jakarta.enterprise.inject.New` 10 | 11 | * `jakarta.enterprise.inject.Specializes` 12 | 13 | * `jakarta.enterprise.inject.Vetoed` 14 | 15 | * `jakarta.enterprise.util.Nonbinding` 16 | 17 | * `jakarta.enterprise.context.Initialized` 18 | 19 | * `jakarta.enterprise.context.Destroyed` 20 | 21 | * `jakarta.enterprise.context.RequestScoped` 22 | 23 | * `jakarta.enterprise.context.SessionScoped` 24 | 25 | * `jakarta.enterprise.context.ApplicationScoped` 26 | 27 | * `jakarta.enterprise.context.Dependent` 28 | 29 | * `jakarta.enterprise.context.ConversationScoped` 30 | 31 | * `jakarta.enterprise.inject.Alternative` 32 | 33 | * `jakarta.enterprise.inject.Typed` 34 | 35 | For example: 36 | [source,java] 37 | ---- 38 | Default defaultLiteral = new Default.Literal(); 39 | 40 | RequestScoped requestScopedLiteral = RequestScoped.Literal.INSTANCE; 41 | 42 | Initialized initializedForApplicationScoped = new Initialized.Literal(ApplicationScoped.class); 43 | 44 | Initialized initializedForRequestScoped = Initialized.Literal.of(RequestScoped.class); 45 | ---- 46 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-adv/cdi-adv010.adoc: -------------------------------------------------------------------------------- 1 | == Using the Configurators Interfaces 2 | 3 | The CDI 2.0 specification defines the following Configurators interfaces, which are used for dynamically defining and modifying CDI objects: 4 | 5 | [width="99%",cols="30%,70%"] 6 | |=== 7 | |Interface |Description 8 | 9 | |`AnnotatedTypeConfigurator` SPI |Helps create and configure the following type metadata: 10 | 11 | `AnnotatedType` 12 | 13 | `AnnotatedField` 14 | 15 | `AnnotatedConstructor` 16 | 17 | `AnnotatedMethod` 18 | 19 | `AnnotatedParameter` 20 | 21 | |`InjectionPointConfigurator` interface |Helps configure an existing `InjectionPoint` instance 22 | 23 | |`BeanAttributesConfigurator` interface |Helps configure a new `BeanAttributes` instance 24 | 25 | |`BeanConfigurator` interface |Helps configure a new `Bean` instance 26 | 27 | |`ObserverMethodConfigurator` interface | Helps configure an `ObserverMethod` instance 28 | 29 | |`ProducerConfigurator` interface |Helps configure a `Producer` instance 30 | |=== 31 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic.adoc: -------------------------------------------------------------------------------- 1 | = Introduction to Jakarta Contexts and Dependency Injection 2 | 3 | This chapter describes Jakarta Contexts and Dependency Injection (CDI) which is one of several Jakarta EE features that help to knit together the web tier and the transactional tier of the Jakarta EE platform. 4 | 5 | include::cdi-basic001.adoc[] 6 | 7 | include::cdi-basic002.adoc[] 8 | 9 | include::cdi-basic003.adoc[] 10 | 11 | include::cdi-basic004.adoc[] 12 | 13 | include::cdi-basic005.adoc[] 14 | 15 | include::cdi-basic006.adoc[] 16 | 17 | include::cdi-basic007.adoc[] 18 | 19 | include::cdi-basic008.adoc[] 20 | 21 | include::cdi-basic009.adoc[] 22 | 23 | include::cdi-basic010.adoc[] 24 | 25 | include::cdi-basic011.adoc[] 26 | 27 | include::cdi-basic012.adoc[] 28 | 29 | include::cdi-basic013.adoc[] 30 | 31 | include::cdi-basic014.adoc[] 32 | 33 | include::cdi-basic015.adoc[] 34 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic003.adoc: -------------------------------------------------------------------------------- 1 | == About Beans 2 | 3 | CDI redefines the concept of a bean beyond its use in other Java technologies, such as the JavaBeans and Jakarta Enterprise Beans technologies. 4 | In CDI, a bean is a source of contextual objects that define application state or logic. 5 | A Jakarta EE component is a bean if the lifecycle of its instances may be managed by the container according to the lifecycle context model defined in the CDI specification. 6 | 7 | More specifically, a bean has the following attributes: 8 | 9 | * A (nonempty) set of bean types 10 | 11 | * A (nonempty) set of qualifiers (see <>) 12 | 13 | * A scope (see <>) 14 | 15 | * Optionally, a bean EL name (see <>) 16 | 17 | * A set of interceptor bindings 18 | 19 | * A bean implementation 20 | 21 | A bean type defines a client-visible type of the bean. Almost any Java type may be a bean type of a bean. 22 | 23 | * A bean type may be an interface, a concrete class, or an abstract 24 | class and may be declared final or have final methods. 25 | 26 | * A bean type may be a parameterized type with type parameters and type variables. 27 | 28 | * A bean type may be an array type. 29 | Two array types are considered identical only if the element type is identical. 30 | 31 | * A bean type may be a primitive type. 32 | Primitive types are considered to be identical to their corresponding wrapper types in `java.lang`. 33 | 34 | * A bean type may be a raw type. 35 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic004.adoc: -------------------------------------------------------------------------------- 1 | == About CDI Managed Beans 2 | 3 | A managed bean is implemented by a Java class, which is called its bean class. 4 | A top-level Java class is a managed bean if it is defined to be a managed bean by any other Jakarta EE technology specification, such as the Jakarta Faces technology specification, or if it meets all the following conditions. 5 | 6 | * It is not a nonstatic inner class. 7 | 8 | * It is a concrete class or is annotated `@Decorator`. 9 | 10 | * It is not annotated with an enterprise bean component-defining annotation or declared as an enterprise bean class in `ejb-jar.xml`. 11 | 12 | * It has an appropriate constructor. 13 | That is, one of the following is the case. 14 | 15 | ** The class has a constructor with no parameters. 16 | 17 | ** The class declares a constructor annotated `@Inject`. 18 | 19 | No special declaration, such as an annotation, is required to define a managed bean. 20 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic005.adoc: -------------------------------------------------------------------------------- 1 | == Beans as Injectable Objects 2 | 3 | The concept of injection has been part of Java technology for some time. 4 | Since the Java EE 5 platform was introduced, annotations have made it possible to inject resources and some other kinds of objects into container-managed objects. 5 | CDI makes it possible to inject more kinds of objects and to inject them into objects that are not container-managed. 6 | 7 | The following kinds of objects can be injected: 8 | 9 | * Almost any Java class 10 | 11 | * Session beans 12 | 13 | * Jakarta EE resources: data sources, Messaging topics, queues, connection factories, and the like 14 | 15 | * Persistence contexts (Jakarta Persistence `EntityManager` objects) 16 | 17 | * Producer fields 18 | 19 | * Objects returned by producer methods 20 | 21 | * Web service references 22 | 23 | * Remote enterprise bean references 24 | 25 | For example, suppose that you create a simple Java class with a method that returns a string: 26 | 27 | [source,java] 28 | ---- 29 | package greetings; 30 | 31 | public class Greeting { 32 | public String greet(String name) { 33 | return "Hello, " + name + "."; 34 | } 35 | } 36 | ---- 37 | 38 | This class becomes a bean that you can then inject into another class. 39 | This bean is not exposed to the EL in this form. 40 | <> explains how you can make a bean accessible to the EL. 41 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic006.adoc: -------------------------------------------------------------------------------- 1 | == Using Qualifiers 2 | 3 | You can use qualifiers to provide various implementations of a particular bean type. 4 | A qualifier is an annotation that you apply to a bean. 5 | A qualifier type is a Java annotation defined as `@Target({METHOD, FIELD, PARAMETER, TYPE})` and `@Retention(RUNTIME)`. 6 | 7 | For example, you could declare an `@Informal` qualifier type and apply it to another class that extends the `Greeting` class. 8 | To declare this qualifier type, use the following code: 9 | 10 | [source,java] 11 | ---- 12 | package greetings; 13 | 14 | import static java.lang.annotation.ElementType.FIELD; 15 | import static java.lang.annotation.ElementType.METHOD; 16 | import static java.lang.annotation.ElementType.PARAMETER; 17 | import static java.lang.annotation.ElementType.TYPE; 18 | import static java.lang.annotation.RetentionPolicy.RUNTIME; 19 | 20 | import java.lang.annotation.Retention; 21 | import static java.lang.annotation.RetentionPolicy.RUNTIME; 22 | import java.lang.annotation.Target; 23 | 24 | import jakarta.inject.Qualifier; 25 | 26 | @Qualifier 27 | @Retention(RUNTIME) 28 | @Target({TYPE, METHOD, FIELD, PARAMETER}) 29 | public @interface Informal {} 30 | ---- 31 | 32 | You can then define a bean class that extends the `Greeting` class and uses this qualifier: 33 | 34 | [source,java] 35 | ---- 36 | package greetings; 37 | 38 | @Informal 39 | public class InformalGreeting extends Greeting { 40 | public String greet(String name) { 41 | return "Hi, " + name + "!"; 42 | } 43 | } 44 | ---- 45 | 46 | Both implementations of the bean can now be used in the application. 47 | 48 | If you define a bean with no qualifier, then the bean automatically has the qualifier `@Default`. 49 | The unannotated `Greeting` class could be declared as follows: 50 | 51 | [source,java] 52 | ---- 53 | package greetings; 54 | 55 | import jakarta.enterprise.inject.Default; 56 | 57 | @Default 58 | public class Greeting { 59 | public String greet(String name) { 60 | return "Hello, " + name + "."; 61 | } 62 | } 63 | ---- 64 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic007.adoc: -------------------------------------------------------------------------------- 1 | == Injecting Beans 2 | 3 | To use the beans you create, you inject them into yet another bean that can then be used by an application, such as a Jakarta Faces application. 4 | For example, you might create a bean called `Printer` into which you would inject one of the `Greeting` beans: 5 | 6 | [source,java] 7 | ---- 8 | import jakarta.inject.Inject; 9 | 10 | public class Printer { 11 | 12 | @Inject Greeting greeting; 13 | ... 14 | } 15 | ---- 16 | 17 | This code injects the `@Default` `Greeting` implementation into the bean. 18 | The following code injects the `@Informal` implementation: 19 | 20 | [source,java] 21 | ---- 22 | import jakarta.inject.Inject; 23 | 24 | public class Printer { 25 | 26 | @Inject @Informal Greeting greeting; 27 | ... 28 | } 29 | ---- 30 | 31 | More is needed for the complete picture of this bean. 32 | Its use of scope needs to be understood. 33 | In addition, for a Jakarta Faces application, the bean needs to be accessible through the EL. 34 | 35 | Now that you can identify the target of the injection, it is important to understand what can be injected and in what context. 36 | Faces 2.3 and above provides producers that enable most important Faces artifacts to be injected. 37 | For detailed information, see the package https://jakarta.ee/specifications/faces/3.0/apidocs/[javadoc^] for `jakarta.faces.annotation`. 38 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic009.adoc: -------------------------------------------------------------------------------- 1 | == Giving Beans EL Names 2 | 3 | To make a bean accessible through the EL, use the `@Named` built-in qualifier: 4 | 5 | [source,java] 6 | ---- 7 | import jakarta.enterprise.context.RequestScoped; 8 | import jakarta.inject.Inject; 9 | import jakarta.inject.Named; 10 | 11 | @Named 12 | @RequestScoped 13 | public class Printer { 14 | 15 | @Inject @Informal Greeting greeting; 16 | ... 17 | } 18 | ---- 19 | 20 | The `@Named` qualifier allows you to access the bean by using the bean name, with the first letter in lowercase. 21 | For example, a Facelets page would refer to the bean as `printer`. 22 | 23 | You can specify an argument to the `@Named` qualifier to use a nondefault name: 24 | 25 | [source,java] 26 | ---- 27 | @Named("MyPrinter") 28 | ---- 29 | 30 | With this annotation, the Facelets page would refer to the bean as `MyPrinter`. 31 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic010.adoc: -------------------------------------------------------------------------------- 1 | == Adding Setter and Getter Methods 2 | 3 | To make the state of the managed bean accessible, add setter and getter methods for that state. 4 | The `createSalutation` method calls the bean's `greet` method, and the `getSalutation` method retrieves the result. 5 | 6 | Once the setter and getter methods have been added, the bean is complete. 7 | The final code looks like this: 8 | 9 | [source,java] 10 | ---- 11 | package greetings; 12 | 13 | import jakarta.enterprise.context.RequestScoped; 14 | import jakarta.inject.Inject; 15 | import jakarta.inject.Named; 16 | 17 | @Named 18 | @RequestScoped 19 | public class Printer { 20 | 21 | @Inject @Informal Greeting greeting; 22 | 23 | private String name; 24 | private String salutation; 25 | 26 | public void createSalutation() { 27 | this.salutation = greeting.greet(name); 28 | } 29 | 30 | public String getSalutation() { 31 | return salutation; 32 | } 33 | 34 | public void setName(String name) { 35 | this.name = name; 36 | } 37 | 38 | public String getName() { 39 | return name; 40 | } 41 | } 42 | ---- 43 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic011.adoc: -------------------------------------------------------------------------------- 1 | == Using a Managed Bean in a Facelets Page 2 | 3 | To use the managed bean in a Facelets page, create a form that uses user interface elements to call its methods and to display their results. 4 | The following example provides a button that asks the user to type a name, retrieves the salutation, and then displays the text in a paragraph below the button: 5 | 6 | [source,xml] 7 | ---- 8 | 9 |

10 |

11 |

13 |

14 | 15 | ---- 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic012.adoc: -------------------------------------------------------------------------------- 1 | == Injecting Objects by Using Producer Methods 2 | 3 | Producer methods provide a way to inject objects that are not beans, objects whose values may vary at runtime, and objects that require custom initialization. 4 | For example, if you want to initialize a numeric value defined by a qualifier named `@MaxNumber`, then you can define the value in a managed bean and then define a producer method, `getMaxNumber`, for it: 5 | 6 | [source,java] 7 | ---- 8 | private int maxNumber = 100; 9 | ... 10 | @Produces @MaxNumber int getMaxNumber() { 11 | return maxNumber; 12 | } 13 | ---- 14 | 15 | When you inject the object in another managed bean, the container automatically invokes the producer method, initializing the value to 100: 16 | 17 | [source,java] 18 | ---- 19 | @Inject @MaxNumber private int maxNumber; 20 | ---- 21 | 22 | If the value can vary at runtime, then the process is slightly different. 23 | For example, the following code defines a producer method that generates a random number defined by a qualifier called `@Random`: 24 | 25 | [source,java] 26 | ---- 27 | private java.util.Random random = 28 | new java.util.Random( System.currentTimeMillis() ); 29 | 30 | java.util.Random getRandom() { 31 | return random; 32 | } 33 | 34 | @Produces @Random int next() { 35 | return getRandom().nextInt(maxNumber); 36 | } 37 | ---- 38 | 39 | When you inject this object in another managed bean, you declare a contextual instance of the object: 40 | 41 | [source,java] 42 | ---- 43 | @Inject @Random Instance randomInt; 44 | ---- 45 | 46 | You then call the `get` method of the `Instance`: 47 | 48 | [source,java] 49 | ---- 50 | this.number = randomInt.get(); 51 | ---- 52 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic013.adoc: -------------------------------------------------------------------------------- 1 | == Configuring a CDI Application 2 | 3 | When your beans are annotated with a scope type, the server recognizes the application as a bean archive and no additional configuration is required. 4 | The possible scope types for CDI beans are listed in <>. 5 | 6 | CDI uses an optional deployment descriptor named `beans.xml`. 7 | Like other Jakarta EE deployment descriptors, the configuration settings in `beans.xml` are used in addition to annotation settings in CDI classes. 8 | The settings in `beans.xml` override the annotation settings if there is a conflict. 9 | An archive must contain the `beans.xml` deployment descriptor only in certain limited situations, described in xref:jakarta-contexts-and-dependency-injection-advanced-topics[xrefstyle=full]. 10 | 11 | For a web application, the `beans.xml` deployment descriptor, if present, must be in the `WEB-INF` directory. 12 | For EJB modules or JAR files, the `beans.xml` deployment descriptor, if present, must be in the `META-INF` directory. 13 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basic/cdi-basic015.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about CDI 2 | 3 | For more information about CDI, see 4 | 5 | * Jakarta Contexts and Dependency Injection specification: + 6 | https://jakarta.ee/specifications/cdi/3.0/[^] 7 | 8 | * Weld - CDI Implementation: + 9 | https://docs.jboss.org/weld/reference/latest/en-US/html/[^] 10 | 11 | * Jakarta Dependency Injection specification: + 12 | https://jakarta.ee/specifications/dependency-injection/2.0/[^] 13 | 14 | * Jakarta Managed beans specification, which is part of the Jakarta EE Platform Specification: + 15 | https://jakarta.ee/specifications/managedbeans/2.0/[^] 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basicexamples/cdi-basicexamples.adoc: -------------------------------------------------------------------------------- 1 | = Running the Basic Contexts and Dependency Injection Examples 2 | 3 | This chapter describes in detail how to build and run simple examples that use CDI. 4 | 5 | include::cdi-basicexamples001.adoc[] 6 | 7 | include::cdi-basicexamples002.adoc[] 8 | 9 | include::cdi-basicexamples003.adoc[] 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-basicexamples/cdi-basicexamples001.adoc: -------------------------------------------------------------------------------- 1 | == Building and Running the CDI Samples 2 | 3 | The examples are in the `_tut-install_/examples/cdi/` directory. 4 | 5 | To build and run the examples, you will do the following: 6 | 7 | . Use NetBeans IDE or the Maven tool to compile and package the example. 8 | 9 | . Use NetBeans IDE or the Maven tool to deploy the example. 10 | 11 | . Run the example in a web browser. 12 | 13 | See xref:using-the-tutorial-examples[xrefstyle=full], for basic information on installing, building, and running the examples. 14 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-bootstrap-se8/cdi-bootstrap-se8.adoc: -------------------------------------------------------------------------------- 1 | = Bootstrapping a CDI Container in Java SE 2 | 3 | This chapter explains how to use the API for bootstrapping a CDI container in Java SE. 4 | This capability allows you to run CDI applications on Java SE and obtain beans, independently of an application server or any Jakarta EE APIs. 5 | 6 | For more information about bootstrapping a CDI container in Java SE, see the _Weld Reference Guide_ at https://weld.cdi-spec.org/documentation/[^]. 7 | 8 | include::cdi-bootstrap-se8001.adoc[] 9 | 10 | include::cdi-bootstrap-se8002.adoc[] 11 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-bootstrap-se8/cdi-bootstrap-se8001.adoc: -------------------------------------------------------------------------------- 1 | == The Bootstrap API 2 | 3 | The API for bootstrapping a CDI container in Java SE consists of the following entities: 4 | 5 | * `jakarta.enterprise.inject.se.SeContainerInitializer` class – Allows you to configure and bootstrap the CDI container. 6 | This class includes the following key methods: 7 | 8 | ** `newInstance()` obtains a `SeContainerInitializer` instance, which allows you to configure the container prior to bootstrapping it. 9 | 10 | ** `initialize()` bootstraps the container. 11 | 12 | * `jakarta.enterprise.inject.se.SeContainer` interface – Provides access to the `BeanManager` instance for programmatic lookup, as defined in the `SeContainer` interface, which is described at https://jakarta.ee/specifications/cdi/3.0/jakarta-cdi-spec-3.0.html#se_container[^]. 13 | -------------------------------------------------------------------------------- /src/main/asciidoc/cdi-bootstrap-se8/cdi-bootstrap-se8002.adoc: -------------------------------------------------------------------------------- 1 | == Configuring the CDI Container 2 | 3 | The configuration of the `SeContainerInitializer` instance allows the explicit addition of elements into an internal *synthetic bean archive*. 4 | The synthetic bean archive represents the set of beans that have been loaded while initializing the container. 5 | The contents of the synthetic bean archive depend on whether discovery is enabled: 6 | 7 | * If discovery is enabled, the synthetic bean archive is created using standard bean discovery rules and contains a superset of all JAR files on the classpath. 8 | Archives that do not include a `beans.xml` file are excluded. 9 | 10 | * If discovery is disabled, and beans are added programmatically, the synthetic bean archive contains only the beans that have been programmatically added. 11 | -------------------------------------------------------------------------------- /src/main/asciidoc/concurrency-utilities/concurrency-utilities.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta Concurrency 2 | 3 | This chapter describes Jakarta Concurrency spec. 4 | 5 | include::concurrency-utilities001.adoc[] 6 | 7 | include::concurrency-utilities002.adoc[] 8 | 9 | include::concurrency-utilities003.adoc[] 10 | 11 | include::concurrency-utilities004.adoc[] 12 | 13 | include::concurrency-utilities005.adoc[] 14 | 15 | include::concurrency-utilities006.adoc[] 16 | 17 | include::concurrency-utilities007.adoc[] 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/concurrency-utilities/concurrency-utilities001.adoc: -------------------------------------------------------------------------------- 1 | == Concurrency Basics 2 | 3 | Concurrency is the concept of executing two or more tasks at the same time (in parallel). 4 | Tasks may include methods (functions), parts of a program, or even other programs. 5 | With current computer architectures, support for multiple cores and multiple processors in a single CPU is very common. 6 | 7 | The Java Platform has always offered support for concurrent programming, which was the basis for implementing many of the services offered by Jakarta EE containers. 8 | Since Java SE 5, additional high-level API support for concurrency was provided by the `java.util.concurrent` package. 9 | 10 | === Threads and Processes 11 | 12 | The two main concurrency concepts are processes and threads. 13 | 14 | Processes are primarily associated with applications running on the operating system (OS). 15 | A process has specific runtime resources to interact with the underlying OS and allocate other resources, such as its own memory, just as the JVM process does. 16 | A JVM is in fact a process. 17 | 18 | The Java programming language and platform are primarily concerned with threads. 19 | 20 | Threads share some features with processes, since both consume resources from the OS or the execution environment. 21 | But threads are easier to create and consume many fewer resources than a process. 22 | 23 | Because threads are so lightweight, any modern CPU that has a couple of cores and a few gigabytes of RAM can handle thousands of threads in a single JVM process. 24 | The precise number of threads will depend on the combined output of the CPU, OS, and RAM available, as well as on correct configuration (tuning) of the JVM. 25 | 26 | Although concurrent programming solves many problems and can improve performance for most applications, there are a number of situations where multiple execution lines (threads or processes) can cause major problems. 27 | These situations include the following: 28 | 29 | * Deadlocks 30 | 31 | * Thread starvation 32 | 33 | * Concurrent accessing of shared resources 34 | 35 | * Situations when the program generates incorrect data 36 | -------------------------------------------------------------------------------- /src/main/asciidoc/concurrency-utilities/concurrency-utilities003.adoc: -------------------------------------------------------------------------------- 1 | == Concurrency and Transactions 2 | 3 | The most basic operations for transactions are commit and rollback, but, in a distributed environment with concurrent processing, it can be difficult to guarantee that commit or rollback operations will be successfully processed, and the transaction can be spread among different threads, CPU cores, physical machines, and networks. 4 | 5 | Ensuring that a rollback operation will successfully execute in such a scenario is crucial. 6 | Concurrency Utilities relies on Jakarta Transactions to implement and support transactions on its components through `jakarta.transaction.UserTransaction`, allowing application developers to explicitly manage transaction boundaries. 7 | More information is available in the Jakarta Transactions specification. 8 | 9 | Optionally, context objects can begin, commit, or roll back transactions, but these objects cannot enlist in parent component transactions. 10 | 11 | The following code snippet illustrates a `Runnable` task that obtains a `UserTransaction` and then starts and commits a transaction while interacting with other transactional components, such as an enterprise bean and a database: 12 | 13 | [source,java] 14 | ---- 15 | public class MyTransactionalTask implements Runnable { 16 | 17 | UserTransaction ut = ... // obtained through JNDI or injection 18 | 19 | public void run() { 20 | 21 | // Start a transaction 22 | ut.begin(); 23 | 24 | // Invoke a Service or an EJB 25 | myEJB.businessMethod(); 26 | 27 | // Update a database entity using an XA JDBC driver 28 | myEJB.updateCustomer(customer); 29 | 30 | // Commit the transaction 31 | ut.commit(); 32 | 33 | } 34 | } 35 | ---- 36 | -------------------------------------------------------------------------------- /src/main/asciidoc/concurrency-utilities/concurrency-utilities004.adoc: -------------------------------------------------------------------------------- 1 | == Concurrency and Security 2 | 3 | Jakarta Concurrency defers most security decisions to the application server implementation. 4 | If, however, the container supports a security context, that context can be propagated to the thread of execution. 5 | The `ContextService` can support several runtime behaviors, and the `security` attribute, if enabled, will propagate the container security principal. 6 | -------------------------------------------------------------------------------- /src/main/asciidoc/concurrency-utilities/concurrency-utilities007.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Jakarta Concurrency 2 | 3 | For more information about concurrency, see 4 | 5 | * Jakarta Concurrency 2.0 specification: + 6 | https://jakarta.ee/specifications/concurrency/2.0/[^] 7 | 8 | * Concurrency Lesson in The Java Tutorials: + 9 | https://docs.oracle.com/javase/tutorial/essential/concurrency/[^] 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/connectorexample/connectorexample.adoc: -------------------------------------------------------------------------------- 1 | = The Resource Adapter Examples 2 | 3 | This chapter describes two examples that demonstrate how to use resource adapters in Jakarta EE applications and how to implement simple resource adapters. 4 | 5 | include::connectorexample001.adoc[] 6 | 7 | include::connectorexample002.adoc[] 8 | 9 | include::connectorexample003.adoc[] 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/connectorexample/connectorexample001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of the Resource Adapter Examples 2 | 3 | The `trading` example shows how to use a simple custom client interface to connect to an EIS from a web application. 4 | The resource adapter in this example implements the outbound contract and the custom client interface. 5 | The `traffic` example shows how to use a message-driven bean (MDB) to process traffic information updates from an EIS. 6 | The resource adapter in this example implements the inbound and work management contracts. 7 | -------------------------------------------------------------------------------- /src/main/asciidoc/dukes-bookstore/dukes-bookstore.adoc: -------------------------------------------------------------------------------- 1 | = Duke's Bookstore Case Study Example 2 | 3 | The Duke's Bookstore example is a simple e-commerce application that illustrates some of the more advanced features of Jakarta Faces technology in combination with Jakarta Contexts and Dependency Injection (CDI), enterprise beans, and the Jakarta Persistence. 4 | Users can select books from an image map, view the bookstore catalog, and purchase books. 5 | No security is used in this application. 6 | 7 | include::dukes-bookstore001.adoc[] 8 | 9 | include::dukes-bookstore002.adoc[] 10 | 11 | include::dukes-bookstore003.adoc[] 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/dukes-bookstore/dukes-bookstore003.adoc: -------------------------------------------------------------------------------- 1 | == Running the Duke's Bookstore Case Study Application 2 | 3 | You can use either NetBeans IDE or Maven to build, package, deploy, and run the Duke's Bookstore application. 4 | 5 | === To Build and Deploy Duke's Bookstore Using NetBeans IDE 6 | 7 | . Make sure that GlassFish Server has been started (see <>). 8 | 9 | . From the File menu, choose Open Project. 10 | 11 | . In the Open Project dialog box, navigate to: 12 | + 13 | ---- 14 | tut-install/examples/case-studies 15 | ---- 16 | 17 | . Select the `dukes-bookstore` folder. 18 | 19 | . Click Open Project. 20 | 21 | . In the Projects tab, right-click the `dukes-bookstore` project and select Build. 22 | + 23 | This will build, package, and deploy Duke's Bookstore to GlassFish Server. 24 | 25 | === To Build and Deploy Duke's Bookstore Using Maven 26 | 27 | . Make sure that GlassFish Server has been started (see <>), as well as the database server (see <>). 28 | 29 | . In a terminal window, go to: 30 | + 31 | ---- 32 | tut-install/examples/case-studies/dukes-bookstore/ 33 | ---- 34 | 35 | . Enter the following command: 36 | + 37 | [source,shell] 38 | ---- 39 | mvn install 40 | ---- 41 | + 42 | This command builds the application and packages it in a WAR file in the `_tut-install_/examples/case-studies/dukes-bookstore/target/` directory. 43 | It then deploys the application to GlassFish Server. 44 | 45 | === To Run Duke's Bookstore 46 | 47 | . In a web browser, enter the following URL: 48 | + 49 | ---- 50 | http://localhost:8080/dukes-bookstore/ 51 | ---- 52 | 53 | . On the Duke's Bookstore main page, click a book in the graphic, or click one of the links at the bottom of the page. 54 | 55 | . Use the pages in the application to view and purchase books. 56 | -------------------------------------------------------------------------------- /src/main/asciidoc/dukes-forest/dukes-forest.adoc: -------------------------------------------------------------------------------- 1 | = Duke's Forest Case Study Example 2 | 3 | This chapter describes Duke's Forest, a simple e-commerce application that contains several web applications and illustrates the use of multiple Jakarta EE APIs. 4 | 5 | include::dukes-forest001.adoc[] 6 | 7 | include::dukes-forest002.adoc[] 8 | 9 | include::dukes-forest003.adoc[] 10 | 11 | include::dukes-forest004.adoc[] 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/dukes-forest/dukes-forest001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of the Duke's Forest Case Study Example 2 | 3 | Duke's Forest is a simple e-commerce application that contains several web applications and illustrates the use of the following Jakarta EE APIs: 4 | 5 | * Jakarta Faces technology, including Ajax 6 | 7 | * Jakarta Contexts and Dependency Injection (CDI) 8 | 9 | * Jakarta RESTful Web Services 10 | 11 | * Jakarta Persistence 12 | 13 | * Jakarta Bean Validation 14 | 15 | * Jakarta Enterprise Beans technology 16 | 17 | * Jakarta Messaging 18 | 19 | The application consists of the following projects. 20 | 21 | * Duke's Store: A web application that has a product catalog, customer self-registration, and a shopping cart. 22 | It also has an administration interface for product, category, and user management. 23 | The project name is `dukes-store`. 24 | 25 | * Duke's Shipment: A web application that provides an interface for order shipment management. 26 | The project name is `dukes-shipment`. 27 | 28 | * Duke's Payment: A web service application that has a RESTful web service for order payment. 29 | The project name is `dukes-payment`. 30 | 31 | * Duke's Resources: A simple Java archive project that contains all resources used by the web projects. 32 | It includes messages, CSS style sheets, images, JavaScript files, and Jakarta Faces composite components. 33 | The project name is `dukes-resources`. 34 | 35 | * Entities: A simple Java archive project that contains all Jakarta Persistence entities. 36 | This project is shared among other projects that use the entities. 37 | The project name is `entities`. 38 | 39 | * Events: A simple Java archive project that contains a POJO class that is used as a CDI event. 40 | The project name is `events`. 41 | -------------------------------------------------------------------------------- /src/main/asciidoc/dukes-forest/dukes-forest003.adoc: -------------------------------------------------------------------------------- 1 | == Building and Deploying the Duke's Forest Case Study Application 2 | 3 | You can use NetBeans IDE or Maven to build and deploy Duke's Forest. 4 | 5 | === To Build and Deploy the Duke's Forest Application Using NetBeans IDE 6 | 7 | . Make sure that GlassFish Server has been started (see <>), as well as the database server (see <>). 8 | 9 | . From the File menu, choose Open Project. 10 | 11 | . In the Open Project dialog box, navigate to: 12 | + 13 | ---- 14 | tut-install/examples/case-studies 15 | ---- 16 | 17 | . Select the `dukes-forest` folder. 18 | 19 | . Select the Open Required Projects check box and click Open Project. 20 | 21 | . Right-click the `dukes-forest` folder and select Build. 22 | + 23 | This task configures the server, creates and populates the database, builds all the subprojects, assembles them into JAR and WAR files, and deploys the `dukes-payment`, `dukes-store,` and `dukes-shipment` applications. 24 | + 25 | To configure the server, this task creates a JDBC security realm named `jdbcRealm`, enables default principal-to-role mapping, and enables single sign-on (SSO) for the HTTP Service. 26 | 27 | === To Build and Deploy the Duke's Forest Application Using Maven 28 | 29 | . Make sure that GlassFish Server has been started (see <>), as well as the database server (see <>). 30 | 31 | . In a terminal window, go to: 32 | + 33 | ---- 34 | tut-install/examples/case-studies/dukes-forest/ 35 | ---- 36 | 37 | . Enter the following command to configure the server, create and populate the database, build all the subprojects, assemble them into JAR and WAR files, and deploy the `dukes-payment`, `dukes-store,` and `dukes-shipment` applications: 38 | + 39 | [source,shell] 40 | ---- 41 | mvn install 42 | ---- 43 | + 44 | To configure the server, this task creates a JDBC security realm named `jdbcRealm`, enables default principal-to-role mapping, and enables single sign-on (SSO) for the HTTP Service. 45 | -------------------------------------------------------------------------------- /src/main/asciidoc/dukes-tutoring/dukes-tutoring.adoc: -------------------------------------------------------------------------------- 1 | = Duke's Tutoring Case Study Example 2 | 3 | The Duke's Tutoring example application is a tracking system for a tutoring center for students. 4 | Students can be checked in and out and can visit the park. 5 | The tutoring center can track attendance and status updates and can store contact information for guardians and students. 6 | Administrators can maintain the tutoring center system. 7 | 8 | include::dukes-tutoring001.adoc[] 9 | 10 | include::dukes-tutoring002.adoc[] 11 | 12 | include::dukes-tutoring003.adoc[] 13 | 14 | include::dukes-tutoring004.adoc[] 15 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-async/ejb-async.adoc: -------------------------------------------------------------------------------- 1 | = Using Asynchronous Method Invocation in Session Beans 2 | 3 | This chapter discusses how to implement asynchronous business methods in session beans and call them from enterprise bean clients. 4 | 5 | include::ejb-async001.adoc[] 6 | 7 | include::ejb-async002.adoc[] 8 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-basicexamples/ejb-basicexamples.adoc: -------------------------------------------------------------------------------- 1 | = Running the Enterprise Bean Examples 2 | 3 | This chapter describes the Jakarta Enterprise Beans examples. 4 | Session beans provide a simple but powerful way to encapsulate business logic within an application. 5 | They can be accessed from remote Java clients, web service clients, and components running in the same server. 6 | 7 | include::ejb-basicexamples001.adoc[] 8 | 9 | include::ejb-basicexamples002.adoc[] 10 | 11 | include::ejb-basicexamples003.adoc[] 12 | 13 | include::ejb-basicexamples004.adoc[] 14 | 15 | include::ejb-basicexamples005.adoc[] 16 | 17 | include::ejb-basicexamples006.adoc[] 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-basicexamples/ejb-basicexamples001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of the Jakarta Enterprise Beans Examples 2 | 3 | In xref:getting-started-with-enterprise-beans[xrefstyle=full], you built a stateless session bean named `ConverterBean`. 4 | This chapter examines the source code of four more session beans: 5 | 6 | * `CartBean`: a stateful session bean that is accessed by a remote client 7 | 8 | * `CounterBean`: a singleton session bean 9 | 10 | * `HelloServiceBean`: a stateless session bean that implements a web service 11 | 12 | * `TimerSessionBean`: a stateless session bean that sets a timer 13 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-basicexamples/ejb-basicexamples006.adoc: -------------------------------------------------------------------------------- 1 | == Handling Exceptions 2 | 3 | The exceptions thrown by enterprise beans fall into two categories: system and application. 4 | 5 | A system exception indicates a problem with the services that support an application. 6 | For example, a connection to an external resource cannot be obtained, or an injected resource cannot be found. 7 | If it encounters a system-level problem, your enterprise bean should throw a `jakarta.ejb.EJBException`. 8 | Because the `EJBException` is a subclass of `RuntimeException`, you do not have to specify it in the `throws` clause of the method declaration. 9 | If a system exception is thrown, the Jakarta Enterprise Beans container might destroy the bean instance. 10 | Therefore, a system exception cannot be handled by the bean's client program, but instead requires intervention by a system administrator. 11 | 12 | An application exception signals an error in the business logic of an enterprise bean. 13 | Application exceptions are typically exceptions that you've coded yourself, such as the `BookException` thrown by the business methods of the `CartBean` example. 14 | When an enterprise bean throws an application exception, the container does not wrap it in another exception. 15 | The client should be able to handle any application exception it receives. 16 | 17 | If a system exception occurs within a transaction, the Enterprise Bean container rolls back the transaction. 18 | However, if an application exception is thrown within a transaction, the container does not roll back the transaction. 19 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-embedded/ejb-embedded.adoc: -------------------------------------------------------------------------------- 1 | = Using the Embedded Enterprise Bean Container 2 | 3 | This chapter demonstrates how to use the embedded enterprise bean container to run enterprise bean applications in the Java SE environment, outside of a Jakarta EE server. 4 | 5 | include::ejb-embedded001.adoc[] 6 | 7 | include::ejb-embedded002.adoc[] 8 | 9 | include::ejb-embedded003.adoc[] 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-embedded/ejb-embedded001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of the Embedded Enterprise Bean Container 2 | 3 | The embedded enterprise bean container is used to access enterprise bean components from client code executed in a Java SE environment. 4 | The container and the client code are executed within the same virtual machine. 5 | The embedded enterprise bean container is typically used for testing enterprise beans without having to deploy them to a server. 6 | 7 | Most of the services present in the enterprise bean container in a Jakarta EE server are available in the embedded enterprise bean container, including injection, container-managed transactions, and security. 8 | Enterprise bean components execute similarly in both embedded and Jakakarta EE environments, and therefore the same enterprise bean can be easily reused in both standalone and networked applications. 9 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted.adoc: -------------------------------------------------------------------------------- 1 | = Getting Started with Enterprise Beans 2 | 3 | This chapter shows how to develop, deploy, and run a simple Jakarta EE application named `converter` that uses an enterprise bean for its business logic. 4 | The purpose of `converter` is to calculate currency conversions among Japanese yen, euros, and US dollars. 5 | The `converter` application consists of an enterprise bean, which performs the calculations, and a web client. 6 | 7 | include::ejb-gettingstarted001.adoc[] 8 | 9 | include::ejb-gettingstarted002.adoc[] 10 | 11 | include::ejb-gettingstarted003.adoc[] 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted001.adoc: -------------------------------------------------------------------------------- 1 | == Starting With Enterprise Beans 2 | 3 | Here's an overview of the steps you'll follow: 4 | 5 | . Create the enterprise bean: `ConverterBean`. 6 | 7 | . Create the web client. 8 | 9 | . Deploy `converter` onto the server. 10 | 11 | . Using a browser, run the web client. 12 | 13 | Before proceeding, make sure that you've done the following: 14 | 15 | * Read xref:overview[xrefstyle=full] 16 | 17 | * Become familiar with enterprise beans (see xref:enterprise-beans[xrefstyle=full]) 18 | 19 | * Started the server (see <>) 20 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted003.adoc: -------------------------------------------------------------------------------- 1 | == Modifying the Jakarta EE Application 2 | 3 | GlassFish Server supports iterative development. 4 | Whenever you make a change to a Jakarta EE application, you must redeploy the application. 5 | 6 | === To Modify a Class File 7 | 8 | To modify a class file in an enterprise bean, you change the source code, recompile it, and redeploy the application. 9 | For example, to update the exchange rate in the `dollarToYen` business method of the `ConverterBean` class, you would follow these steps. 10 | 11 | To modify `ConverterServlet`, the procedure is the same. 12 | 13 | . Edit `ConverterBean.java` and save the file. 14 | 15 | . Recompile the source file. 16 | 17 | .. To recompile `ConverterBean.java` in NetBeans IDE, right-click the `converter` project and select Run. 18 | + 19 | This recompiles the `ConverterBean.java` file, replaces the old class file in the build directory, and redeploys the application to GlassFish Server. 20 | 21 | .. Recompile `ConverterBean.java` using Maven. 22 | 23 | ... In a terminal window, go to the `_tut-install_/examples/ejb/converter/` directory. 24 | 25 | ... Enter the following command: 26 | + 27 | [source,shell] 28 | ---- 29 | mvn install 30 | ---- 31 | + 32 | This command repackages and deploys the application. 33 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-intro/ejb-intro.adoc: -------------------------------------------------------------------------------- 1 | = Enterprise Beans 2 | 3 | Enterprise beans are Jakarta EE components that implement Jakarta Enterprise Beans technology. 4 | Enterprise beans run in the Enterprise Bean container, a runtime environment within GlassFish Server (see <>). 5 | Although transparent to the application developer, the Enterprise Bean container provides system-level services, such as transactions and security, to its enterprise beans. 6 | These services enable you to quickly build and deploy enterprise beans, which form the core of transactional Jakarta EE applications. 7 | 8 | include::ejb-intro001.adoc[] 9 | 10 | include::ejb-intro002.adoc[] 11 | 12 | include::ejb-intro003.adoc[] 13 | 14 | include::ejb-intro004.adoc[] 15 | 16 | include::ejb-intro005.adoc[] 17 | 18 | include::ejb-intro006.adoc[] 19 | 20 | include::ejb-intro007.adoc[] 21 | 22 | include::ejb-intro008.adoc[] 23 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-intro/ejb-intro005.adoc: -------------------------------------------------------------------------------- 1 | == The Contents of an Enterprise Bean 2 | 3 | To develop an enterprise bean, you must provide the following files. 4 | 5 | * Enterprise bean class: Implements the business methods of the enterprise bean and any lifecycle callback methods. 6 | 7 | * Business interfaces: Define the business methods implemented by the enterprise bean class. 8 | A business interface is not required if the enterprise bean exposes a local, no-interface view. 9 | 10 | * Helper classes: Other classes needed by the enterprise bean class, such as exception and utility classes. 11 | 12 | Package the programming artifacts in the preceding list either into an Enterprise Bean JAR file (a stand-alone module that stores the enterprise bean) or within a web application archive (WAR) module. 13 | See <> and <> for more information. 14 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-intro/ejb-intro006.adoc: -------------------------------------------------------------------------------- 1 | == Naming Conventions for Enterprise Beans 2 | 3 | Because enterprise beans are composed of multiple parts, it's useful to follow a naming convention for your applications. 4 | <> summarizes the conventions for the example beans in this tutorial. 5 | 6 | [[naming-conventions-for-enterprise-beans-2]] 7 | .Naming Conventions for Enterprise Beans 8 | [width="63%",cols="40%,30%,30%"] 9 | |=== 10 | |Item |Syntax |Example 11 | 12 | |Enterprise bean name |__name__Bean |`AccountBean` 13 | 14 | |Enterprise bean class |__name__Bean |`AccountBean` 15 | 16 | |Business interface |_name_ |`Account` 17 | |=== 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/ejb-intro/ejb-intro008.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Enterprise Beans 2 | 3 | For more information on Jakarta Enterprise Beans technology, see the Jakarta Enterprise Beans 4.0 specification: + 4 | https://jakarta.ee/specifications/enterprise-beans/4.0/[^] 5 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-advanced-cc/faces-advanced-cc.adoc: -------------------------------------------------------------------------------- 1 | = Composite Components: Advanced Topics and an Example 2 | 3 | This chapter describes the advanced features of composite components in Jakarta Faces technology. 4 | 5 | include::faces-advanced-cc001.adoc[] 6 | 7 | include::faces-advanced-cc002.adoc[] 8 | 9 | include::faces-advanced-cc003.adoc[] 10 | 11 | include::faces-advanced-cc004.adoc[] 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-advanced-cc/faces-advanced-cc002.adoc: -------------------------------------------------------------------------------- 1 | == Invoking a Managed Bean 2 | 3 | To enable a composite component to handle server-side data 4 | 5 | . Invoke a managed bean in one of the following ways: 6 | 7 | * Pass the reference of the managed bean to the composite component. 8 | 9 | * Directly use the properties of the managed bean. 10 | + 11 | The example application described in <> shows how to use a managed bean with a composite component by passing the reference of the managed bean to the component. 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-advanced-cc/faces-advanced-cc003.adoc: -------------------------------------------------------------------------------- 1 | == Validating Composite Component Values 2 | 3 | Jakarta Faces provides the following tags for validating values of input components. 4 | These tags can be used with the `composite:valueHolder` or the `composite:editableValueHolder` tag. 5 | 6 | <> lists commonly used validator tags. 7 | See <> for details and a complete list. 8 | 9 | [[validator-tags]] 10 | .Validator Tags 11 | [width="70%",cols="15%,55%"] 12 | |=== 13 | |Tag Name |Description 14 | 15 | |`f:validateBean` |Delegates the validation of the local value to the Bean Validation API. 16 | 17 | |`f:validateRegex` a|Uses the `pattern` attribute to validate the wrapping component. 18 | The entire pattern is matched against the `String` value of the component. 19 | If it matches, it is valid. 20 | 21 | |`f:validateRequired` a|Enforces the presence of a value. 22 | Has the same effect as setting the `required` element of a composite component's attribute to `true`. 23 | |=== 24 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-ajax/faces-ajax.adoc: -------------------------------------------------------------------------------- 1 | = Using Ajax with Jakarta Faces Technology 2 | 3 | This chapter describes using Ajax functionality in Jakarta Faces web applications. 4 | Ajax is an acronym for Asynchronous JavaScript and XML, a group of web technologies that enable creation of dynamic and highly responsive web applications. 5 | Using Ajax, web applications can retrieve content from the server without interfering with the display on the client. 6 | In the Jakarta EE platform, Jakarta Faces technology provides built-in support for Ajax. 7 | 8 | include::faces-ajax001.adoc[] 9 | 10 | include::faces-ajax002.adoc[] 11 | 12 | include::faces-ajax003.adoc[] 13 | 14 | include::faces-ajax004.adoc[] 15 | 16 | include::faces-ajax005.adoc[] 17 | 18 | include::faces-ajax006.adoc[] 19 | 20 | include::faces-ajax007.adoc[] 21 | 22 | include::faces-ajax008.adoc[] 23 | 24 | include::faces-ajax009.adoc[] 25 | 26 | include::faces-ajax010.adoc[] 27 | 28 | include::faces-ajax011.adoc[] 29 | 30 | include::faces-ajax012.adoc[] 31 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-ajax/faces-ajax002.adoc: -------------------------------------------------------------------------------- 1 | == Using Ajax Functionality with Jakarta Faces Technology 2 | 3 | Ajax functionality can be added to a Jakarta Faces application in one of the following ways: 4 | 5 | * Adding the required JavaScript code to an application 6 | 7 | * Using the built-in Ajax resource library 8 | 9 | In earlier releases of the Jakarta EE platform, Jakarta Faces applications provided Ajax functionality by adding the necessary JavaScript to the web page. 10 | In the Jakarta EE platform, standard Ajax support is provided by a built-in JavaScript resource library. 11 | 12 | With the support of this JavaScript resource library, Jakarta Faces standard UI components, such as buttons, labels, or text fields, can be enabled for Ajax functionality. 13 | You can also load this resource library and use its methods directly from within the managed bean code. 14 | The next sections of the tutorial describe the use of the built-in Ajax resource library. 15 | 16 | In addition, because the Jakarta Faces technology component model can be extended, custom components can be created with Ajax functionality. 17 | 18 | The tutorial examples include an Ajax version of the `guessnumber` application, `ajaxguessnumber`. 19 | See <> for more information. 20 | 21 | The Ajax specific `f:ajax` tag and its attributes are explained in the next sections. 22 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-ajax/faces-ajax005.adoc: -------------------------------------------------------------------------------- 1 | == Monitoring Events on the Client 2 | 3 | To monitor ongoing Ajax requests, use the `onevent` attribute of the `f:ajax` tag. 4 | The value of this attribute is the name of a JavaScript function. 5 | Jakarta Faces calls the `onevent` function at each stage of the processing of an Ajax request: begin, complete, and success. 6 | 7 | When calling the JavaScript function assigned to the `onevent` property, Jakarta Faces passes a data object to it. 8 | The data object contains the properties listed in <>. 9 | 10 | [[properties-of-the-onevent-data-object]] 11 | .Properties of the onevent Data Object 12 | [width="60%",cols="15%,45%"] 13 | |=== 14 | |Property |Description 15 | 16 | |`responseXML` |The response to the Ajax call in XML format 17 | 18 | |`responseText` |The response to the Ajax call in text format 19 | 20 | |`responseCode` |The response to the Ajax call in numeric code 21 | 22 | |`source` |The source of the current Ajax event: the DOM element 23 | 24 | |`status` |The status of the current Ajax call: `begin`, `complete`, or `success` 25 | 26 | |`type` |The type of the Ajax call: `event` 27 | |=== 28 | 29 | By using the `status` property of the data object, you can identify the current status of the Ajax request and monitor its progress. 30 | In the following example, `monitormyajaxevent` is a JavaScript function that monitors the Ajax request sent by the event: 31 | 32 | [source,xml] 33 | ---- 34 | 35 | ---- 36 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-ajax/faces-ajax006.adoc: -------------------------------------------------------------------------------- 1 | == Handling Errors 2 | 3 | Jakarta Faces handles Ajax errors through use of the `onerror` attribute of the `f:ajax` tag. 4 | The value of this attribute is the name of a JavaScript function. 5 | 6 | When there is an error in processing a Ajax request, Jakarta Faces calls the defined `onerror` JavaScript function and passes a data object to it. 7 | The data object contains all the properties available for the `onevent` attribute and, in addition, the following properties: 8 | 9 | * `description` 10 | 11 | * `errorName` 12 | 13 | * `errorMessage` 14 | 15 | The `type` is `error`. 16 | The `status` property of the data object contains one of the valid error values listed in <>. 17 | 18 | [[valid-error-values-for-the-data-object-status-property]] 19 | .Valid Error Values for the Data Object status Property 20 | [width="60%",cols="15%,45%"] 21 | |=== 22 | |Values |Description 23 | 24 | |`emptyResponse` |No Ajax response from server. 25 | 26 | |`httpError` |One of the valid HTTP errors: `request.status==null` or `request.status==undefined` or `request.status<200` or `request.status>=300`. 27 | 28 | |`malformedXML` |The Ajax response is not well formed. 29 | 30 | |`serverError` |The Ajax response contains an `error` element. 31 | |=== 32 | 33 | In the following example, any errors that occurred in processing the Ajax request are handled by the `handlemyajaxerror` JavaScript function: 34 | 35 | [source,xml] 36 | ---- 37 | 38 | ---- 39 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-ajax/faces-ajax007.adoc: -------------------------------------------------------------------------------- 1 | == Receiving an Ajax Response 2 | 3 | After the application sends an Ajax request, it is processed on the server side, and a response is sent back to the client. 4 | As described earlier, Ajax allows for partial updating of web pages. 5 | To enable such partial updating, Jakarta Faces technology allows for partial processing of the view. 6 | The handling of the response is defined by the `render` attribute of the `f:ajax` tag. 7 | 8 | Similar to the `execute` attribute, the `render` attribute defines which sections of the page will be updated. 9 | The value of a `render` attribute can be one or more component `id` values, one of the keywords `@this`, `@all`, `@none`, or `@form`, or an EL expression. 10 | In the following example, the `render` attribute identifies an output component to be displayed when the button component is clicked (the default event for a command button): 11 | 12 | [source,xml] 13 | ---- 14 | 15 | 16 | 17 | 18 | ---- 19 | 20 | [NOTE] 21 | Behind the scenes, once again the `faces.ajax.request()` method handles the response. 22 | It registers a response-handling callback when the original request is created. 23 | When the response is sent back to the client, the callback is invoked. 24 | This callback automatically updates the client-side DOM to reflect the rendered response. 25 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-ajax/faces-ajax008.adoc: -------------------------------------------------------------------------------- 1 | == Ajax Request Lifecycle 2 | 3 | An Ajax request varies from other typical Jakarta Faces requests, and its processing is also handled differently by the Jakarta Faces lifecycle. 4 | 5 | As described in <>, when an Ajax request is received, the state associated with that request is captured by the `jakarta.faces.context.PartialViewContext`. 6 | This object provides access to information such as which components are targeted for processing/rendering. 7 | The `processPartial` method of `PartialViewContext` uses this information to perform partial component tree processing and rendering. 8 | 9 | The `execute` attribute of the `f:ajax` tag identifies which segments of the server-side component tree should be processed. 10 | Because components can be uniquely identified in the Jakarta Faces component tree, it is easy to identify and process a single component, a few components, or a whole tree. 11 | This is made possible by the `visitTree` method of the `UIComponent` class. 12 | The identified components then run through the Jakarta Faces request lifecycle phases. 13 | 14 | Similar to the `execute` attribute, the `render` attribute identifies which segments of the Jakarta Faces component tree need to be rendered during the render response phase. 15 | 16 | During the render response phase, the `render` attribute is examined. 17 | The identified components are found and asked to render themselves and their children. 18 | The components are then packaged up and sent back to the client as a response. 19 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-ajax/faces-ajax009.adoc: -------------------------------------------------------------------------------- 1 | == Grouping of Components 2 | 3 | The previous sections describe how to associate a single UI component with Ajax functionality. 4 | You can also associate Ajax with more than one component at a time by grouping them together on a page. 5 | The following example shows how a number of components can be grouped by using the `f:ajax` tag: 6 | 7 | [source,xml] 8 | ---- 9 | 10 | 11 | 12 | 13 | 14 | 15 | ---- 16 | 17 | In the example, neither component is associated with any Ajax `event` or `render` attributes yet. 18 | Therefore, no action will take place in case of user input. 19 | You can associate the above components with an `event` and a `render` attribute as follows: 20 | 21 | [source,xml] 22 | ---- 23 | 24 | 25 | 26 | 27 | 28 | 29 | ---- 30 | 31 | In the updated example, when the user clicks either component, the updated results will be displayed for all components. 32 | You can further fine-tune the Ajax action by adding specific events to each of the components, in which case Ajax functionality becomes cumulative. 33 | Consider the following example: 34 | 35 | [source,xml] 36 | ---- 37 | 38 | ... 39 | 40 | 41 | 42 | ... 43 | 44 | ---- 45 | 46 | Now the button component will fire an Ajax action in case of a `mouseover` event as well as a mouse-click event. 47 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-ajax/faces-ajax012.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Ajax in Jakarta Faces Technology 2 | 3 | For more information on Ajax in Jakarta Faces Technology, see 4 | 5 | * Jakarta Faces project website: + 6 | https://jakarta.ee/specifications/faces/4.0/[^] 7 | 8 | * https://jakarta.ee/specifications/faces/3.0/jsdoc/jsf.ajax.html[Jakarta Faces JavaScript Library APIs^] 9 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-configure/faces-configure.adoc: -------------------------------------------------------------------------------- 1 | = Configuring Jakarta Faces Applications 2 | 3 | This chapter describes additional configuration tasks required when you create large and complex applications. 4 | 5 | include::faces-configure001.adoc[] 6 | 7 | include::faces-configure002.adoc[] 8 | 9 | include::faces-configure003.adoc[] 10 | 11 | include::faces-configure004.adoc[] 12 | 13 | include::faces-configure006.adoc[] 14 | 15 | include::faces-configure007.adoc[] 16 | 17 | include::faces-configure008.adoc[] 18 | 19 | include::faces-configure009.adoc[] 20 | 21 | include::faces-configure010.adoc[] 22 | 23 | include::faces-configure011.adoc[] 24 | 25 | include::faces-configure012.adoc[] 26 | 27 | include::faces-configure013.adoc[] 28 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-configure/faces-configure001.adoc: -------------------------------------------------------------------------------- 1 | == Introduction to Configuring Jakarta Faces Applications 2 | 3 | The process of building and deploying simple Jakarta Faces applications is described in earlier chapters of this tutorial, including xref:getting-started-with-web-applications[xrefstyle=full], xref:introduction-to-facelets[xrefstyle=full], xref:using-ajax-with-jakarta-faces-technology[xrefstyle=full] and xref:composite-components-advanced-topics-and-an-example[xrefstyle=full] When you create large and complex applications, however, various additional configuration tasks are required. 4 | These tasks include the following: 5 | 6 | * Registering managed beans with the application so that all parts of the application have access to them 7 | 8 | * Configuring managed beans and model beans so that they are instantiated with the proper values when a page makes reference to them 9 | 10 | * Defining navigation rules for each of the pages in the application so that the application has a smooth page flow, if nondefault navigation is needed 11 | 12 | * Packaging the application to include all the pages, resources, and other files so that the application can be deployed on any compliant container 13 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-configure/faces-configure007.adoc: -------------------------------------------------------------------------------- 1 | == Using Default Validators 2 | 3 | In addition to the validators you declare on the components, you can also specify zero or more default validators in the application configuration resource file. 4 | The default validator applies to all `jakarta.faces.component.UIInput` instances in a view or component tree and is appended after the local defined validators. 5 | Here is an example of a default validator registered in the application configuration resource file: 6 | 7 | [source,xml] 8 | ---- 9 | 10 | 11 | 12 | jakarta.faces.Bean 13 | 14 | 15 | 16 | ---- 17 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-configure/faces-configure008.adoc: -------------------------------------------------------------------------------- 1 | == Registering a Custom Validator 2 | 3 | If the application developer provides an implementation of the `jakarta.faces.validator.Validator` interface to perform validation, you must register this custom validator either by using the `@FacesValidator` annotation, as described in <>, or by using the `validator` XML element in the application configuration resource file: 4 | 5 | [source,xml] 6 | ---- 7 | 8 | ... 9 | FormatValidator 10 | 11 | myapplication.validators.FormatValidator 12 | 13 | 14 | ... 15 | formatPatterns 16 | java.lang.String 17 | 18 | 19 | ---- 20 | 21 | Attributes specified in a `validator` tag override any settings in the `@FacesValidator` annotation. 22 | 23 | The `validator-id` and `validator-class` elements are required subelements. 24 | The `validator-id` element represents the identifier under which the `Validator` class should be registered. 25 | This ID is used by the tag class corresponding to the custom `validator` tag. 26 | 27 | The `validator-class` element represents the fully qualified class name of the `Validator` class. 28 | 29 | The `attribute` element identifies an attribute associated with the `Validator` implementation. 30 | It has required `attribute-name` and `attribute-class` subelements. 31 | The `attribute-name` element refers to the name of the attribute as it appears in the `validator` tag. 32 | The `attribute-class` element identifies the Java type of the value associated with the attribute. 33 | 34 | <> explains how to implement the `Validator` interface. 35 | 36 | <> explains how to reference the validator from the page. 37 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-configure/faces-configure009.adoc: -------------------------------------------------------------------------------- 1 | == Registering a Custom Converter 2 | 3 | As is the case with a custom validator, if the application developer creates a custom converter, you must register it with the application either by using the `@FacesConverter` annotation, as described in <>, or by using the `converter` XML element in the application configuration resource file. 4 | Here is a hypothetical `converter` configuration for `CreditCardConverter` from the Duke's Bookstore case study: 5 | 6 | [source,xml] 7 | ---- 8 | 9 | 10 | Converter for credit card numbers that normalizes 11 | the input to a standard format 12 | 13 | CreditCardConverter 14 | 15 | dukesbookstore.converters.CreditCardConverter 16 | 17 | 18 | ---- 19 | 20 | Attributes specified in a `converter` tag override any settings in the `@FacesConverter` annotation. 21 | 22 | The `converter` element represents a `jakarta.faces.convert.Converter` implementation and contains required `converter-id` and `converter-class` elements. 23 | 24 | The `converter-id` element identifies an ID that is used by the `converter` attribute of a UI component tag to apply the converter to the component's data. 25 | <> includes an example of referencing the custom converter from a component tag. 26 | 27 | The `converter-class` element identifies the `Converter` implementation. 28 | 29 | <> explains how to create a custom converter. 30 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-custom/faces-custom.adoc: -------------------------------------------------------------------------------- 1 | = Creating Custom UI Components and Other Custom Objects 2 | 3 | This chapter describes creating custom components for applications that have additional functionality not provided by standard Jakarta Faces components. 4 | 5 | include::faces-custom001.adoc[] 6 | 7 | include::faces-custom002.adoc[] 8 | 9 | include::faces-custom003.adoc[] 10 | 11 | include::faces-custom004.adoc[] 12 | 13 | include::faces-custom005.adoc[] 14 | 15 | include::faces-custom006.adoc[] 16 | 17 | include::faces-custom007.adoc[] 18 | 19 | include::faces-custom008.adoc[] 20 | 21 | include::faces-custom009.adoc[] 22 | 23 | include::faces-custom010.adoc[] 24 | 25 | include::faces-custom011.adoc[] 26 | 27 | include::faces-custom012.adoc[] 28 | 29 | include::faces-custom013.adoc[] 30 | 31 | include::faces-custom014.adoc[] 32 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-custom/faces-custom004.adoc: -------------------------------------------------------------------------------- 1 | == Steps for Creating a Custom Component 2 | 3 | You can apply the following steps while developing your own custom component. 4 | 5 | . Create a custom component class that does the following: 6 | 7 | .. Overrides the `getFamily` method to return the component family, which is used to look up renderers that can render the component 8 | 9 | .. Includes the rendering code or delegates it to a renderer (explained in <>) 10 | 11 | .. Enables component attributes to accept expressions 12 | 13 | .. Queues an event on the component if the component generates events 14 | 15 | .. Saves and restores the component state 16 | 17 | . [[create-custom-component-step-2, Step 2]] Delegate rendering to a renderer if your component does not handle the rendering. 18 | To do this: 19 | 20 | .. Create a custom renderer class by extending `jakarta.faces.render.Renderer`. 21 | 22 | .. Register the renderer to a render kit. 23 | 24 | . Register the component. 25 | 26 | . Create an event handler if your component generates events. 27 | 28 | . Create a tag library descriptor (TLD) that defines the custom tag. 29 | 30 | See <> and <> for information on registering the custom component and the renderer. 31 | The section <> discusses how to use the custom component in a Jakarta Faces page. 32 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-develop/faces-develop.adoc: -------------------------------------------------------------------------------- 1 | = Developing with Jakarta Faces Technology 2 | 3 | This chapter provides an overview of managed beans and explains how to write methods and properties of managed beans that are used by a Jakarta Faces application. 4 | This chapter also introduces the Bean Validation feature. 5 | 6 | include::faces-develop001.adoc[] 7 | 8 | include::faces-develop002.adoc[] 9 | 10 | include::faces-develop003.adoc[] 11 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-el/faces-el.adoc: -------------------------------------------------------------------------------- 1 | = Expression Language 2 | 3 | This chapter introduces the Expression Language (also referred to as the EL), which provides an important mechanism for enabling the presentation layer (web pages) to communicate with the application logic (managed beans). 4 | The EL is used by several Jakarta EE technologies, such as Jakarta Faces technology, Jakarta Server Pages technology, and Dependency Injection for Jakarta EE (CDI). 5 | The EL can also be used in stand-alone environments. 6 | This chapter only covers the use of the EL in Jakarta EE containers. 7 | 8 | include::faces-el001.adoc[] 9 | 10 | include::faces-el002.adoc[] 11 | 12 | include::faces-el003.adoc[] 13 | 14 | include::faces-el004.adoc[] 15 | 16 | include::faces-el005.adoc[] 17 | 18 | include::faces-el006.adoc[] 19 | 20 | include::faces-el007.adoc[] 21 | 22 | include::faces-el008.adoc[] 23 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-el/faces-el001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of the EL 2 | 3 | The EL allows page authors to use simple expressions to dynamically access data from JavaBeans components. 4 | For example, the `test` attribute of the following conditional tag is supplied with an EL expression that compares 0 with the number of items in the session-scoped bean named `cart`. 5 | 6 | [source,xml] 7 | ---- 8 | 9 | ... 10 | 11 | ---- 12 | 13 | See <> for more information on how to use the EL in Jakarta Faces applications. 14 | 15 | To summarize, the EL provides a way to use simple expressions to perform the following tasks: 16 | 17 | * Dynamically read application data stored in JavaBeans components, various data structures, and implicit objects 18 | 19 | * Dynamically write data, such as user input into forms, to JavaBeans components 20 | 21 | * Invoke arbitrary static and public methods 22 | 23 | * Dynamically perform arithmetic, boolean, and string operations 24 | 25 | * Dynamically construct collection objects and perform operations on collections 26 | 27 | In a Jakarta Faces page, an EL expression can be used either in static text or in the attribute of a custom tag or standard action. 28 | 29 | Finally, the EL provides a pluggable API for resolving expressions so that custom resolvers that can handle expressions not already supported by the EL can be implemented. 30 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-el/faces-el005.adoc: -------------------------------------------------------------------------------- 1 | == Operators 2 | 3 | In addition to the `.` and `[]` operators discussed in <>, the EL provides the following operators, which can be used in rvalue expressions only. 4 | 5 | * Arithmetic: `+`, `-` (binary), `*`, `/` and `div`, `%` and `mod`, `-` (unary). 6 | 7 | * String concatenation: `+=`. 8 | 9 | * Logical: `and`, `&&`, `or`, `||`, `not`, `!`. 10 | 11 | * Relational: `==`, `eq`, `!=`, `ne`, `<`, `lt`, `>`, `gt`, `\<=`, `ge`, `>=`, `le`. 12 | Comparisons can be made against other values or against Boolean, string, integer, or floating-point literals. 13 | 14 | * Empty: The `empty` operator is a prefix operation that can be used to determine whether a value is `null` or empty. 15 | 16 | * Conditional: `A ? B : C`. Evaluate `B` or `C`, depending on the result of the evaluation of `A`. 17 | 18 | * Lambda expression: `\->`, the arrow token. 19 | 20 | * Assignment: `=`. 21 | 22 | * Semicolon: `;`. 23 | 24 | The precedence of operators, highest to lowest, left to right, is as follows: 25 | 26 | * `[] .` 27 | 28 | * `()` (used to change the precedence of operators) 29 | 30 | * `-` (unary) `not ! empty` 31 | 32 | * `* / div % mod` 33 | 34 | * `+ -` (binary) 35 | 36 | * `+=` 37 | 38 | * `<> \<= >= lt gt le ge` 39 | 40 | * `== != eq ne` 41 | 42 | * `&& and` 43 | 44 | * `|| or` 45 | 46 | * `? :` 47 | 48 | * `\->` 49 | 50 | * `=` 51 | 52 | * `;` 53 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-el/faces-el006.adoc: -------------------------------------------------------------------------------- 1 | == Reserved Words 2 | 3 | The following words are reserved for the EL and should not be used as identifiers: 4 | 5 | [options="noheader",width="50%"] 6 | |=== 7 | |`and` |`or` |`not` |`eq` 8 | 9 | |`ne` |`lt` |`gt` |`le` 10 | 11 | |`ge` |`true` |`false` |`null` 12 | 13 | |`instanceof`|`empty`|`div` |`mod` 14 | |=== -------------------------------------------------------------------------------- /src/main/asciidoc/faces-el/faces-el007.adoc: -------------------------------------------------------------------------------- 1 | == Examples of EL Expressions 2 | 3 | <> contains example EL expressions and the result of evaluating them. 4 | 5 | [[example-expressions]] 6 | .Example Expressions 7 | [width="80%",cols="40%,40%"] 8 | |=== 9 | |EL Expression |Result 10 | 11 | |`${1 > (4/2)}` |`false` 12 | 13 | |`${4.0 >= 3}` |`true` 14 | 15 | |`${100.0 == 100}` |`true` 16 | 17 | |`${(10*10) ne 100}` |`false` 18 | 19 | |`${'a' > 'b'}` |`false` 20 | 21 | |`${'hip' lt 'hit'}` |`true` 22 | 23 | |`${4 > 3}` |`true` 24 | 25 | |`${1.2E4 + 1.4}` |`12001.4` 26 | 27 | |`${3 div 4}` |`0.75` 28 | 29 | |`${10 mod 4}` |`2` 30 | 31 | |`${((x, y) -> x + y)(3, 5.5)}` |`8.5` 32 | 33 | |`[1,2,3,4].stream().sum()` |`10` 34 | 35 | |`[1,3,5,2].stream().sorted().toList()` |`[1, 2, 3, 5]` 36 | 37 | |`${!empty param.Add}` |`False` if the request parameter named `Add` is `null` or an empty string 38 | 39 | |`${pageContext.request.contextPath}` |The context path 40 | 41 | |`${sessionScope.cart.numberOfItems}` |The value of the `numberOfItems` property of the session-scoped attribute named `cart` 42 | 43 | |`${param['mycom.productId']}` |The value of the request parameter named `mycom.productId` 44 | 45 | |`${header["host"]}` |The host 46 | 47 | |`${departments[deptName]}` |The value of the entry named `deptName` in the `departments` map 48 | 49 | |`${requestScope['jakarta.servlet.forward.servlet_path']}` |The value of the request-scoped attribute named `jakarta.servlet.forward.servlet_path` 50 | 51 | |`#{customer.lName}` |Gets the value of the property `lName` from the `customer` bean during an initial request; sets the value of `lName` during a postback 52 | 53 | |`#{customer.calcTotal}` |The return value of the method `calcTotal` of the `customer` bean 54 | |=== 55 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-el/faces-el008.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about the Expression Language 2 | 3 | For more information about the Expression Language, see 4 | 5 | * The Expression Language 4.0 specification: + 6 | https://jakarta.ee/specifications/expression-language/4.0/[^] 7 | 8 | * The EL specification website: + 9 | https://github.com/eclipse-ee4j/el-ri/tree/master/spec[^] 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-facelets/faces-facelets.adoc: -------------------------------------------------------------------------------- 1 | = Introduction to Facelets 2 | 3 | The term Facelets refers to the view declaration language for Jakarta Faces technology. 4 | Facelets is a part of the Jakarta Faces specification and also the preferred presentation technology for building Jakarta Faces technology–based applications. 5 | Jakarta Server Pages technology, previously used as the presentation technology for Jakarta Faces, does not support all the new features available in Jakarta Faces in the Jakarta EE platform. 6 | Jakarta Server Pages technology is considered to be a deprecated presentation technology for Jakarta Faces. 7 | 8 | include::faces-facelets001.adoc[] 9 | 10 | include::faces-facelets002.adoc[] 11 | 12 | include::faces-facelets003.adoc[] 13 | 14 | include::faces-facelets004.adoc[] 15 | 16 | include::faces-facelets005.adoc[] 17 | 18 | include::faces-facelets006.adoc[] 19 | 20 | include::faces-facelets007.adoc[] 21 | 22 | include::faces-facelets008.adoc[] 23 | 24 | include::faces-facelets009.adoc[] 25 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-facelets/faces-facelets002.adoc: -------------------------------------------------------------------------------- 1 | == The Lifecycle of a Facelets Application 2 | 3 | The Jakarta Faces specification defines the lifecycle of a Jakarta Faces application. 4 | For more information on this lifecycle, see <>. 5 | The following steps describe that process as applied to a Facelets-based application. 6 | 7 | . When a client, such as a browser, makes a new request to a page that is created using Facelets, a new component tree or `jakarta.faces.component.UIViewRoot` is created and placed in the `FacesContext`. 8 | 9 | . [[step-2-of-lifecycle-of-facelets, Step 2]] The `UIViewRoot` is applied to the Facelets, and the view is populated with components for rendering. 10 | 11 | . The newly built view is rendered back as a response to the client. 12 | 13 | . On rendering, the state of this view is stored for the next request. 14 | The state of input components and form data is stored. 15 | 16 | . The client may interact with the view and request another view or change from the Jakarta Faces application. 17 | At this time, the saved view is restored from the stored state. 18 | 19 | . The restored view is once again passed through the Jakarta Faces lifecycle, which eventually will either generate a new view or re-render the current view if there were no validation problems and no action was triggered. 20 | 21 | . If the same view is requested, the stored view is rendered once again. 22 | 23 | . If a new view is requested, then the process described in <> is continued. 24 | 25 | . The new view is then rendered back as a response to the client. 26 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-facelets/faces-facelets007.adoc: -------------------------------------------------------------------------------- 1 | == Relocatable Resources 2 | 3 | You can place a resource tag in one part of a page and specify that it be rendered in another part of the page. 4 | To do this, you use the `target` attribute of a tag that specifies a resource. 5 | Acceptable values for this attribute are as follows. 6 | 7 | * "`head`" renders the resource in the `head` element. 8 | 9 | * "`body`" renders the resource in the `body` element. 10 | 11 | * "`form`" renders the resource in the `form` element. 12 | 13 | For example, the following `h:outputScript` tag is placed within an `h:form` element, but it renders the JavaScript in the `head` element: 14 | 15 | [source,xml] 16 | ---- 17 | 18 | 19 | 20 | ---- 21 | 22 | The `h:outputStylesheet` tag also supports resource relocation, in a similar way. 23 | 24 | Relocatable resources are essential for composite components that use stylesheets and can also be useful for composite components that use JavaScript. 25 | See <> for an example. 26 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-intro/faces-intro.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta Faces Technology 2 | 3 | Jakarta Faces technology is a server-side component framework for building Java technology–based web applications. 4 | 5 | include::faces-intro001.adoc[] 6 | 7 | include::faces-intro002.adoc[] 8 | 9 | include::faces-intro003.adoc[] 10 | 11 | include::faces-intro004.adoc[] 12 | 13 | include::faces-intro005.adoc[] 14 | 15 | include::faces-intro006.adoc[] 16 | 17 | include::faces-intro007.adoc[] 18 | 19 | include::faces-intro008.adoc[] 20 | 21 | include::faces-intro009.adoc[] 22 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-intro/faces-intro001.adoc: -------------------------------------------------------------------------------- 1 | == Introduction to Jakarta Faces Technology 2 | 3 | Jakarta Faces technology consists of the following: 4 | 5 | * An API for representing components and managing their state; handling events, server-side validation, and data conversion; defining page navigation; supporting internationalization and accessibility; and providing extensibility for all these features 6 | 7 | * Tag libraries for adding components to web pages and for connecting components to server-side objects 8 | 9 | Jakarta Faces technology provides a well-defined programming model and various tag libraries. 10 | The tag libraries contain tag handlers that implement the component tags. 11 | These features significantly ease the burden of building and maintaining web applications with server-side user interfaces (UIs). 12 | With minimal effort, you can complete the following tasks. 13 | 14 | * Create a web page. 15 | 16 | * Drop components onto a web page by adding component tags. 17 | 18 | * Bind components on a page to server-side data. 19 | 20 | * Wire component-generated events to server-side application code. 21 | 22 | * Save and restore application state beyond the life of server requests. 23 | 24 | * Reuse and extend components through customization. 25 | 26 | This chapter provides an overview of Jakarta Faces technology. 27 | After explaining what a Jakarta Faces application is and reviewing some of the primary benefits of using Jakarta Faces technology, this chapter describes the process of creating a simple Jakarta Faces application. 28 | This chapter also introduces the Jakarta Faces lifecycle by describing the example Jakarta Faces application and its progression through the lifecycle stages. 29 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-intro/faces-intro008.adoc: -------------------------------------------------------------------------------- 1 | == Partial Processing and Partial Rendering 2 | 3 | The Jakarta Faces lifecycle spans all of the execute and render processes of an application. 4 | It is also possible to process and render only parts of an application, such as a single component. 5 | For example, the Jakarta Faces Ajax framework can generate requests containing information on which particular component may be processed and which particular component may be rendered back to the client. 6 | 7 | Once such a partial request enters the Jakarta Faces lifecycle, the information is identified and processed by a `jakarta.faces.context.PartialViewContext` object. 8 | The Jakarta Faces lifecycle is still aware of such Ajax requests and modifies the component tree accordingly. 9 | 10 | The `execute` and `render` attributes of the `f:ajax` tag are used to identify which components may be executed and rendered. 11 | For more information on these attributes, see xref:using-ajax-with-jakarta-faces-technology[xrefstyle=full]. 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-intro/faces-intro009.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Jakarta Faces Technology 2 | 3 | For more information on Jakarta Faces technology, see 4 | 5 | * Jakarta Faces 3.0 specification: + 6 | https://jakarta.ee/specifications/faces/3.0/[^] 7 | 8 | * Mojarra website: + 9 | https://eclipse-ee4j.github.io/mojarra/[^] 10 | 11 | For additional samples, see the GlassFish samples at https://github.com/eclipse-ee4j/glassfish-samples/tree/master/ws/jakartaee9[^]. 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-page-core/faces-page-core.adoc: -------------------------------------------------------------------------------- 1 | = Using Converters, Listeners, and Validators 2 | 3 | The previous chapter described components and explained how to add them to a web page. 4 | This chapter provides information on adding more functionality to the components through converters, listeners, and validators. 5 | 6 | * Converters are used to convert data that is received from the input components. 7 | Converters allow an application to bring the strongly typed features of the Java programming language into the String-based world of HTTP servlet programming. 8 | 9 | * Listeners are used to listen to the events happening in the page and perform actions as defined. 10 | 11 | * Validators are used to validate the data that is received from the input components. 12 | Validators allow an application to express constraints on form input data to ensure that the necessary requirements are met before the input data is processed. 13 | 14 | include::faces-page-core001.adoc[] 15 | 16 | include::faces-page-core002.adoc[] 17 | 18 | include::faces-page-core003.adoc[] 19 | 20 | include::faces-page-core004.adoc[] 21 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-page/faces-page.adoc: -------------------------------------------------------------------------------- 1 | = Using Jakarta Faces Technology in Web Pages 2 | 3 | Web pages (Facelets pages, in most cases) represent the presentation layer for web applications. 4 | The process of creating web pages for a Jakarta Faces application includes using component tags to add components to the page and wire them to backing beans, validators, listeners, converters, and other server-side objects that are associated with the page. 5 | 6 | This chapter explains how to create web pages using various types of component and core tags. 7 | In the next chapter, you will learn about adding converters, validators, and listeners to component tags to provide additional functionality to components. 8 | 9 | Many of the examples in this chapter are taken from xref:dukes-bookstore-case-study-example[xrefstyle=full] 10 | 11 | include::faces-page001.adoc[] 12 | 13 | include::faces-page002.adoc[] 14 | 15 | include::faces-page003.adoc[] 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-ws/faces-ws.adoc: -------------------------------------------------------------------------------- 1 | = Using WebSockets with Jakarta Faces Technology 2 | 3 | This chapter describes using WebSockets in Jakarta Faces web applications. 4 | 5 | include::faces-ws001.adoc[] 6 | 7 | include::faces-ws002.adoc[] 8 | 9 | include::faces-ws003.adoc[] 10 | 11 | include::faces-ws004.adoc[] 12 | 13 | include::faces-ws005.adoc[] 14 | 15 | include::faces-ws006.adoc[] 16 | 17 | include::faces-ws007.adoc[] 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-ws/faces-ws001.adoc: -------------------------------------------------------------------------------- 1 | == About WebSockets in Jakarta Faces 2 | 3 | You use the `f:websocket tag` in a view to allow server-side communications to be pushed to all instances of a socket containing the same channel name. 4 | When the communication is received, an `onmessage`, client-side JavaScript event handler can be set that is called whenever a push arrives from the server. 5 | 6 | The server side of a WebSocket communication has the ability to push out messages. 7 | You can do this using `jakarta.faces.push.PushContext`, which is an injectable context, allowing a server push to a named channel. 8 | -------------------------------------------------------------------------------- /src/main/asciidoc/faces-ws/faces-ws007.adoc: -------------------------------------------------------------------------------- 1 | == Using Ajax With WebSockets 2 | 3 | If you want to perform complex UI updates depending on the received push message, you can nest the `f:ajax` tag inside the `f:websocket` tag. 4 | See the following example: 5 | 6 | [source,xml] 7 | ---- 8 | 9 | ... (some complex UI here) ... 10 | 11 | 12 | 13 | 14 | 15 | 16 | ---- 17 | 18 | Here, the push message simply represents the ajax event name. 19 | You can use any custom event name. 20 | 21 | [source,javascript] 22 | ---- 23 | someChannel.send("someEvent"); 24 | ---- 25 | 26 | An alternative is to combine the `f:websocket` tag with the `h:commandScript` tag. 27 | The `` references exactly the ``. 28 | 29 | For example: 30 | 31 | [source,xml] 32 | ---- 33 | 34 | ... (some complex UI here) ... 35 | 36 | 37 | 38 | 39 | 40 | ---- 41 | 42 | If you pass a `Map` or a JavaBean as the push message object, then all entries or properties will transparently be available as request parameters in the command script method `#{bean.pushed}`. 43 | -------------------------------------------------------------------------------- /src/main/asciidoc/images/eclipse_foundation_logo_tiny.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/eclipse-ee4j/jakartaee-tutorial/631afef9121fc4cfaae552701984a3cb0796bd5e/src/main/asciidoc/images/eclipse_foundation_logo_tiny.png -------------------------------------------------------------------------------- /src/main/asciidoc/index.adoc: -------------------------------------------------------------------------------- 1 | = The Jakarta(R) EE Tutorial 2 | :authors: Jakarta Platform Team, https://projects.eclipse.org/projects/ee4j.jakartaee-platform 3 | :email: https://accounts.eclipse.org/mailing-list/jakartaee-platform-dev 4 | :revnumber: Release 9.1 5 | :revdate: December 2021 6 | :revremark: Final 7 | :version-label!: 8 | :doctype: book 9 | :license: Eclipse Public License v. 2.0 10 | :source-highlighter: coderay 11 | :toc: left 12 | :toclevels: 2 13 | :sectnumlevels: 1 14 | :sectnums: 15 | :partnums: 16 | :part-signifier: Part 17 | :chapter-signifier: Chapter 18 | :autoxref-chapter: 1 19 | :autoxref-chaptersectlevel: 1 20 | :autoxref-imagecaption: Figure %d-%d 21 | :autoxref-tablecaption: Table %d-%d 22 | 23 | include::title.adoc[] 24 | 25 | include::preface.adoc[] 26 | 27 | include::partintro.adoc[] 28 | 29 | include::partplatform.adoc[] 30 | 31 | include::partwebtier.adoc[] 32 | 33 | include::partbeanvalidation.adoc[] 34 | 35 | include::partcdi.adoc[] 36 | 37 | include::partwebsvcs.adoc[] 38 | 39 | include::partentbeans.adoc[] 40 | 41 | include::partpersist.adoc[] 42 | 43 | include::partmessaging.adoc[] 44 | 45 | include::partsecurity.adoc[] 46 | 47 | include::partsupporttechs.adoc[] 48 | 49 | include::partcasestudies.adoc[] 50 | -------------------------------------------------------------------------------- /src/main/asciidoc/injection/injection.adoc: -------------------------------------------------------------------------------- 1 | = Injection 2 | 3 | This chapter provides an overview of injection in Jakarta EE and describes the two injection mechanisms provided by the platform: resource injection and dependency injection. 4 | 5 | Jakarta EE provides injection mechanisms that enable your objects to obtain references to resources and other dependencies without having to instantiate them directly. 6 | You declare the required resources and other dependencies in your classes by decorating fields or methods with one of the annotations that mark the field as an injection point. 7 | The container then provides the required instances at runtime. 8 | Injection simplifies your code and decouples it from the implementations of its dependencies. 9 | 10 | include::injection001.adoc[] 11 | 12 | include::injection002.adoc[] 13 | 14 | include::injection003.adoc[] 15 | -------------------------------------------------------------------------------- /src/main/asciidoc/injection/injection001.adoc: -------------------------------------------------------------------------------- 1 | == Resource Injection 2 | 3 | Resource injection enables you to inject any resource available in the JNDI namespace into any container-managed object, such as a servlet, an enterprise bean, or a managed bean. 4 | For example, you can use resource injection to inject data sources, connectors, or custom resources available in the JNDI namespace. 5 | 6 | The type you use for the reference to the injected instance is usually an interface, which decouples your code from the implementation of the resource. 7 | 8 | For example, the following code injects a data source object that provides connections to the default Apache Derby database shipped with 9 | Eclipse GlassFish Server: 10 | 11 | [source,java] 12 | ---- 13 | public class MyServlet extends HttpServlet { 14 | @Resource(name="java:comp/DefaultDataSource") 15 | private javax.sql.DataSource dsc; 16 | ... 17 | } 18 | ---- 19 | 20 | In addition to field-based injection as in the preceding example, you can inject resources using method-based injection: 21 | 22 | [source,java] 23 | ---- 24 | public class MyServlet extends HttpServlet { 25 | private javax.sql.DataSource dsc; 26 | ... 27 | @Resource(name="java:comp/DefaultDataSource") 28 | public void setDsc(java.sql.DataSource ds) { 29 | dsc = ds; 30 | } 31 | } 32 | ---- 33 | 34 | To use method-based injection, the setter method must follow the JavaBeans conventions for property names: The method name must begin with `set`, have a `void` return type, and have only one parameter. 35 | 36 | The `@Resource` annotation is in the `jakarta.annotation` package and is defined in the Jakarta Annotations spec. 37 | Resource injection resolves by name, so it is not typesafe: the type of the resource object is not known at compile time, so you can get runtime errors if the types of the object and its reference do not match. 38 | -------------------------------------------------------------------------------- /src/main/asciidoc/injection/injection002.adoc: -------------------------------------------------------------------------------- 1 | == Dependency Injection 2 | 3 | Dependency injection enables you to turn regular Java classes into managed objects and to inject them into any other managed object. 4 | Using dependency injection, your code can declare dependencies on any managed object. 5 | The container automatically provides instances of these dependencies at the injection points at runtime, and it also manages the lifecycle of these instances for you. 6 | 7 | Dependency injection in Jakarta EE defines scopes, which determine the lifecycle of the objects that the container instantiates and injects. 8 | For example, a managed object that is only needed to respond to a single client request (such as a currency converter) has a different scope than a managed object that is needed to process multiple client requests within a session (such as a shopping cart). 9 | 10 | You can define managed objects (also called managed beans) that you can later inject by assigning a scope to a regular class: 11 | 12 | [source,java] 13 | ---- 14 | @jakarta.enterprise.context.RequestScoped 15 | public class CurrencyConverter { ... } 16 | ---- 17 | 18 | Use the `jakarta.inject.Inject` annotation to inject managed beans; for example: 19 | 20 | [source,java] 21 | ---- 22 | public class MyServlet extends HttpServlet { 23 | @Inject CurrencyConverter cc; 24 | ... 25 | } 26 | ---- 27 | 28 | As opposed to resource injection, dependency injection is typesafe because it resolves by type. 29 | To decouple your code from the implementation of the managed bean, you can reference the injected instances using an interface type and have your managed bean implement that interface. 30 | 31 | For more information about dependency injection, see xref:introduction-to-jakarta-contexts-and-dependency-injection[xrefstyle=full] and the Jakarta Contexts and Dependency Injection spec. -------------------------------------------------------------------------------- /src/main/asciidoc/injection/injection003.adoc: -------------------------------------------------------------------------------- 1 | == The Main Differences between Resource Injection and Dependency Injection 2 | 3 | <> lists the main differences between resource injection and dependency injection. 4 | 5 | [[differences-between-resource-injection-and-dependency-injection]] 6 | .Differences between Resource Injection and Dependency Injection 7 | [options="header",width="99%",cols="25%,20%,20%,20%,15%"] 8 | |=== 9 | |Injection Mechanism |Can Inject JNDI Resources Directly |Can Inject Regular Classes Directly |Resolves By |Typesafe 10 | 11 | |Resource Injection |Yes |No |Resource name |No 12 | 13 | |Dependency Injection |No |Yes |Type |Yes 14 | |=== 15 | -------------------------------------------------------------------------------- /src/main/asciidoc/interceptors/interceptors.adoc: -------------------------------------------------------------------------------- 1 | = Using Jakarta EE Interceptors 2 | 3 | This chapter discusses how to create interceptor classes and methods that interpose on method invocations or lifecycle events on a target class. 4 | 5 | include::interceptors001.adoc[] 6 | 7 | include::interceptors002.adoc[] 8 | 9 | include::interceptors003.adoc[] 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/jaxrs-advanced/jaxrs-advanced.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta REST: Advanced Topics and an Example 2 | 3 | Jakarta RESTful Web Services (Jakarta REST) is designed to make it easy to develop applications that use the REST architecture. 4 | This chapter describes advanced features of Jakarta REST. 5 | If you are new to Jakarta REST, see xref:building-restful-web-services-with-jakarta-rest[xrefstyle=full] before you proceed with this chapter. 6 | 7 | Jakarta REST is integrated with Jakarta Contexts and Dependency Injection (CDI), Jakarta Enterprise Beans technology, and Jakarta Servlet technology. 8 | 9 | include::jaxrs-advanced001.adoc[] 10 | 11 | include::jaxrs-advanced002.adoc[] 12 | 13 | include::jaxrs-advanced003.adoc[] 14 | 15 | include::jaxrs-advanced004.adoc[] 16 | 17 | include::jaxrs-advanced005.adoc[] 18 | 19 | include::jaxrs-advanced006.adoc[] 20 | 21 | include::jaxrs-advanced007.adoc[] 22 | 23 | include::jaxrs-advanced008.adoc[] 24 | -------------------------------------------------------------------------------- /src/main/asciidoc/jaxrs-advanced/jaxrs-advanced004.adoc: -------------------------------------------------------------------------------- 1 | == Integrating Jakarta REST with Jakarta Enterprise Beans Technology and CDI 2 | 3 | Jakarta REST works with Jakarta Enterprise Beans technology and Jakarta Contexts and Dependency Injection (CDI). 4 | 5 | In general, for Jakarta REST to work with enterprise beans, you need to annotate the class of a bean with `@Path` to convert it to a root resource class. 6 | You can use the `@Path` annotation with stateless session beans and singleton POJO beans. 7 | 8 | The following code snippet shows a stateless session bean and a singleton bean that have been converted to Jakarta REST root resource classes. 9 | 10 | [source,java] 11 | ---- 12 | @Stateless 13 | @Path("stateless-bean") 14 | public class StatelessResource {...} 15 | 16 | @Singleton 17 | @Path("singleton-bean") 18 | public class SingletonResource {...} 19 | ---- 20 | 21 | Session beans can also be used for subresources. 22 | 23 | Jakarta REST and CDI have slightly different component models. 24 | By default, Jakarta REST root resource classes are managed in the request scope, and no annotations are required for specifying the scope. 25 | CDI managed beans annotated with `@RequestScoped` or `@ApplicationScoped` can be converted to Jakarta REST resource classes. 26 | 27 | The following code snippet shows a Jakarta REST resource class. 28 | 29 | [source,java] 30 | ---- 31 | @Path("/employee/{id}") 32 | public class Employee { 33 | public Employee(@PathParam("id") String id) {...} 34 | } 35 | 36 | @Path("{lastname}") 37 | public final class EmpDetails {...} 38 | ---- 39 | 40 | The following code snippet shows this Jakarta REST resource class converted to a CDI bean. 41 | The beans must be proxyable, so the `Employee` class requires a nonprivate constructor with no parameters, and the `EmpDetails` class must not be `final`. 42 | 43 | [source,java] 44 | ---- 45 | @Path("/employee/{id}") 46 | @RequestScoped 47 | public class Employee { 48 | public Employee() {...} 49 | 50 | @Inject 51 | public Employee(@PathParam("id") String id) {...} 52 | } 53 | 54 | @Path("{lastname}") 55 | @RequestScoped 56 | public class EmpDetails {...} 57 | ---- 58 | -------------------------------------------------------------------------------- /src/main/asciidoc/jaxrs-advanced/jaxrs-advanced005.adoc: -------------------------------------------------------------------------------- 1 | == Conditional HTTP Requests 2 | 3 | Jakarta REST provides support for conditional `GET` and `PUT` HTTP requests. 4 | Conditional `GET` requests help save bandwidth by improving the efficiency of client processing. 5 | 6 | A `GET` request can return a Not Modified (304) response if the representation has not changed since the previous request. 7 | For example, a website can return 304 responses for all its static images that have not changed since the previous request. 8 | 9 | A `PUT` request can return a Precondition Failed (412) response if the representation has been modified since the last request. 10 | The conditional `PUT` can help avoid the lost update problem. 11 | 12 | Conditional HTTP requests can be used with the `Last-Modified` and `ETag` headers. 13 | The `Last-Modified` header can represent dates with granularity of one second. 14 | 15 | [source,java] 16 | ---- 17 | @Path("/employee/{joiningdate}") 18 | public class Employee { 19 | 20 | Date joiningdate; 21 | 22 | @GET 23 | @Produces("application/xml") 24 | public Employee(@PathParam("joiningdate") Date joiningdate, 25 | @Context Request req, 26 | @Context UriInfo ui) { 27 | 28 | this.joiningdate = joiningdate; 29 | ... 30 | this.tag = computeEntityTag(ui.getRequestUri()); 31 | if (req.getMethod().equals("GET")) { 32 | Response.ResponseBuilder rb = req.evaluatePreconditions(tag); 33 | if (rb != null) { 34 | throw new WebApplicationException(rb.build()); 35 | } 36 | } 37 | } 38 | } 39 | ---- 40 | 41 | In this code snippet, the constructor of the `Employee` class computes the entity tag from the request URI and calls the `request.evaluatePreconditions` method with that tag. 42 | If a client request returns an `If-none-match` header with a value that has the same entity tag that was computed, `evaluate.Preconditions` returns a pre-filled-out response with a 304 status code and an entity tag set that may be built and returned. 43 | -------------------------------------------------------------------------------- /src/main/asciidoc/jaxrs-client/jaxrs-client.adoc: -------------------------------------------------------------------------------- 1 | = Accessing REST Resources with the Jakarta REST Client API 2 | 3 | This chapter describes the Jakarta REST Client API and includes examples of how to access REST resources using the Java programming language. 4 | 5 | Jakarta REST provides a client API for accessing REST resources from other Java applications. 6 | 7 | include::jaxrs-client001.adoc[] 8 | 9 | include::jaxrs-client002.adoc[] 10 | 11 | include::jaxrs-client003.adoc[] 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/jaxrs/jaxrs.adoc: -------------------------------------------------------------------------------- 1 | = Building RESTful Web Services with Jakarta REST 2 | 3 | This chapter describes the REST architecture, RESTful web services, and the Jakarta RESTful Web Services. 4 | 5 | Jakarta REST makes it easy for developers to build RESTful web services using the Java programming language. 6 | 7 | include::jaxrs001.adoc[] 8 | 9 | include::jaxrs002.adoc[] 10 | 11 | include::jaxrs003.adoc[] 12 | 13 | include::jaxrs004.adoc[] 14 | -------------------------------------------------------------------------------- /src/main/asciidoc/jaxrs/jaxrs004.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Jakarta REST 2 | 3 | For more information about RESTful web services and Jakarta REST, see 4 | 5 | * "Fielding Dissertation: Chapter 5: Representational State Transfer (REST)": + 6 | https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm[^] 7 | 8 | * RESTful Web Services, by Leonard Richardson and Sam Ruby, available from O'Reilly Media at https://www.oreilly.com/library/view/restful-web-services/9780596529260/[^] 9 | 10 | * Jakarta RESTful Web Services 3.0 specification: + 11 | https://jakarta.ee/specifications/restful-ws/3.0/[^] 12 | 13 | * Jersey project: + 14 | https://eclipse-ee4j.github.io/jersey/[^] 15 | -------------------------------------------------------------------------------- /src/main/asciidoc/jaxws/jaxws.adoc: -------------------------------------------------------------------------------- 1 | = Building Web Services with Jakarta XML Web Services 2 | 3 | This chapter describes Jakarta XML Web Services, a technology for building web services and clients that communicate using XML. 4 | XML Web Services allows developers to write message-oriented as well as Remote Procedure Call–oriented (RPC-oriented) web services. 5 | 6 | include::jaxws001.adoc[] 7 | 8 | include::jaxws002.adoc[] 9 | 10 | include::jaxws003.adoc[] 11 | 12 | include::jaxws004.adoc[] 13 | 14 | include::jaxws005.adoc[] 15 | -------------------------------------------------------------------------------- /src/main/asciidoc/jaxws/jaxws001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of Jakarta XML Web Services 2 | 3 | In Jakarta XML Web Services, a web service operation invocation is represented by an XML-based protocol, such as SOAP. 4 | The SOAP specification defines the envelope structure, encoding rules, and conventions for representing web service invocations and responses. 5 | These calls and responses are transmitted as SOAP messages (XML files) over HTTP. 6 | 7 | Although SOAP messages are complex, the XML Web Services API hides this complexity from the application developer. 8 | On the server side, the developer specifies the web service operations by defining methods in an interface written in the Java programming language. 9 | The developer also codes one or more classes that implement those methods. 10 | Client programs are also easy to code. 11 | A client creates a proxy (a local object representing the service) and then simply invokes methods on the proxy. 12 | With XML Web Services, the developer does not generate or parse SOAP messages. 13 | It is the XML Web Services runtime system that converts the API calls and responses to and from SOAP messages. 14 | 15 | With XML Web Services, clients and web services have a big advantage: the platform independence of the Java programming language. 16 | In addition, XML Web Services is not restrictive: A XML Web Services client can access a web service that is not running on the Java platform and vice versa. 17 | This flexibility is possible because XML Web Services uses technologies defined by the W3C: HTTP, SOAP, and WSDL. 18 | WSDL specifies an XML format for describing a service as a set of endpoints operating on messages. 19 | 20 | [NOTE] 21 | Several files in the XML Web Services examples depend on the port that you specified when you installed GlassFish Server. 22 | These tutorial examples assume that the server runs on the default port, 8080. 23 | They do not run with a nondefault port setting. 24 | -------------------------------------------------------------------------------- /src/main/asciidoc/jaxws/jaxws004.adoc: -------------------------------------------------------------------------------- 1 | == Web Services Interoperability and Jakarta XML Web Services 2 | 3 | Jakarta XML Web Services supports the Web Services Interoperability (WS-I) Basic Profile Version 1.1. 4 | The WS-I Basic Profile is a document that clarifies the SOAP 1.1 and WSDL 1.1 specifications to promote SOAP interoperability. 5 | For links related to WS-I, see <>. 6 | 7 | To support WS-I Basic Profile Version 1.1, the JAX-WS runtime supports doc/literal and rpc/literal encodings for services, static ports, dynamic proxies, and the Dynamic Invocation Interface (DII). 8 | -------------------------------------------------------------------------------- /src/main/asciidoc/jaxws/jaxws005.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Jakarta XML Web Services 2 | 3 | For more information about Jakarta XML Web Services and related technologies, see 4 | 5 | * Jakarta XML Web Services 3.0 specification: + 6 | https://jakarta.ee/specifications/xml-web-services/3.0/[^] 7 | 8 | * Jakarta XML Web Services home: + 9 | https://eclipse-ee4j.github.io/metro-jax-ws/[^] 10 | 11 | * Simple Object Access Protocol (SOAP) 1.2 W3C Note: + 12 | https://www.w3.org/TR/soap/[^] 13 | 14 | * Web Services Description Language (WSDL) 1.1 W3C Note: + 15 | https://www.w3.org/TR/wsdl[^] 16 | 17 | * WS-I Basic Profile 1.2 and 2.0: + 18 | http://www.ws-i.org[^] 19 | -------------------------------------------------------------------------------- /src/main/asciidoc/jms-concepts/jms-concepts.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta Messaging Concepts 2 | 3 | This chapter provides an introduction to Jakarta Messaging, a Java API that allows applications to create, send, receive, and read messages using reliable, asynchronous, loosely coupled communication. 4 | 5 | include::jms-concepts001.adoc[] 6 | 7 | include::jms-concepts002.adoc[] 8 | 9 | include::jms-concepts003.adoc[] 10 | 11 | include::jms-concepts004.adoc[] 12 | 13 | include::jms-concepts005.adoc[] 14 | 15 | include::jms-concepts006.adoc[] 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/jms-concepts/jms-concepts006.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Jakarta Messaging 2 | 3 | For more information about Jakarta Messaging, see 4 | 5 | * Jakarta Messaging website: + 6 | https://projects.eclipse.org/projects/ee4j.jms[^] 7 | 8 | * Jakarta Messaging specification, version 3.0, available from: + 9 | https://jakarta.ee/specifications/messaging/3.0/[^] 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/jms-examples/jms-examples.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta Messaging Examples 2 | 3 | This chapter provides examples that show how to use Jakarta Messaging in various kinds of Jakarta EE applications. 4 | 5 | include::jms-examples001.adoc[] 6 | 7 | include::jms-examples002.adoc[] 8 | 9 | include::jms-examples003.adoc[] 10 | 11 | include::jms-examples004.adoc[] 12 | 13 | include::jms-examples005.adoc[] 14 | 15 | include::jms-examples006.adoc[] 16 | 17 | include::jms-examples007.adoc[] 18 | 19 | include::jms-examples008.adoc[] 20 | 21 | include::jms-examples009.adoc[] 22 | 23 | include::jms-examples010.adoc[] 24 | -------------------------------------------------------------------------------- /src/main/asciidoc/jms-examples/jms-examples001.adoc: -------------------------------------------------------------------------------- 1 | == Building and Running Jakarta Messaging Examples 2 | 3 | The examples are in the `_tut-install_/examples/jms/` directory. 4 | 5 | To build and run each example: 6 | 7 | . Use NetBeans IDE or Maven to compile, package, and in some cases deploy the example. 8 | 9 | . Use NetBeans IDE, Maven, or the `appclient` command to run the application client, or use the browser to run the web application examples. 10 | 11 | Before you deploy or run the examples, you need to create resources for them. 12 | Some examples have a `glassfish-resources.xml` file that is used to create resources for that example and others. 13 | You can use the `asadmin` command to create the resources. 14 | 15 | To use the `asadmin` and `appclient` commands, you need to put the GlassFish Server `bin` directories in your command path, as described in <>. 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/jsonb/jsonb.adoc: -------------------------------------------------------------------------------- 1 | = JSON Binding 2 | 3 | This chapter describes the Jakarta JSON Binding. 4 | JSON is a data exchange format widely used in web services and other connected applications. 5 | For a brief overview of JSON, see <>. 6 | 7 | The https://jakarta.ee/specifications/jsonb/[Jakarta JSON Binding^] specification provides a standard binding layer (metadata and runtime) between Java classes and JSON documents. 8 | One Jakarta JSON Binding reference implementation is Yasson, which is developed through Eclipse.org and is included as part of GlassFish Server. 9 | 10 | You can learn more about Yasson at https://projects.eclipse.org/projects/ee4j.yasson[^]. 11 | 12 | include::jsonb001.adoc[] 13 | 14 | include::jsonb002.adoc[] 15 | 16 | include::jsonb003.adoc[] 17 | 18 | include::jsonb004.adoc[] 19 | -------------------------------------------------------------------------------- /src/main/asciidoc/jsonb/jsonb003.adoc: -------------------------------------------------------------------------------- 1 | == Running the jsonbbasics Example Application 2 | 3 | This section describes how to build and run the `jsonbbasics` example application. 4 | This example is a web application that demonstrates how to serialize an object to JSON and how to deserialize JSON to an object. 5 | 6 | The `jsonbbasics` example application is in the `_tut-install_/examples/web/jsonb/jsonbbasics` directory. 7 | 8 | === Components of the jsonbbasics Example Application 9 | 10 | The `jsonbbasics` example application contains the following files. 11 | 12 | * Two Jakarta Faces pages. 13 | 14 | ** The `index.xhtml` page contains a form to collect data that is used to create a `Person` object. 15 | 16 | ** The `jsongenerated.xhtml` page contains a text area that displays the data in JSON format. 17 | 18 | * The `JsonbBean.java` managed bean, which is a session-scoped managed bean that stores the data from the form and directs the navigation between the Facelets pages. 19 | This file contains code that uses the JSON Binding API. 20 | 21 | === Running the jsonbbasics Example Application 22 | 23 | This section describes how to run the `jsonbbasics` example application from the command line using Maven. 24 | 25 | To run the jsonbbasics example application using Maven: 26 | 27 | . Make sure that GlassFish Server has been started (see <>). 28 | 29 | . In a terminal window, go to: 30 | + 31 | ---- 32 | tut-install/examples/web/jsonb/jsonbbasics 33 | ---- 34 | 35 | . Enter the following command to deploy the application: 36 | + 37 | [source,shell] 38 | ---- 39 | mvn install 40 | ---- 41 | 42 | . Open a web browser window and enter the following address: 43 | + 44 | ---- 45 | http://localhost:8080/jsonbbasics/ 46 | ---- 47 | 48 | . Enter data on form and click Serialize to JSON to submit the form. 49 | The following page shows the JSON format of the object data. 50 | 51 | . Click Deserialize JSON. 52 | The index page displays and contains the fields populated from the object data. 53 | -------------------------------------------------------------------------------- /src/main/asciidoc/jsonb/jsonb004.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about the Jakarta JSON Binding 2 | 3 | For more information on Jakarta JSON Binding, see: 4 | 5 | * Jakarta JSON Binding spec: + 6 | https://jakarta.ee/specifications/jsonb/[^] 7 | 8 | * Specification project: + 9 | https://github.com/eclipse-ee4j/jsonb-api[^] 10 | 11 | * Yasson (Implementation): + 12 | https://projects.eclipse.org/projects/ee4j.yasson[^] 13 | -------------------------------------------------------------------------------- /src/main/asciidoc/jsonp/jsonp.adoc: -------------------------------------------------------------------------------- 1 | = JSON Processing 2 | 3 | This chapter describes Jakarta JSON Processing. 4 | JSON is a data exchange format widely used in web services and other connected applications. 5 | Jakarta JSON Processing provides an API to parse, transform, and query JSON data using the object model or the streaming model. 6 | 7 | include::jsonp001.adoc[] 8 | 9 | include::jsonp002.adoc[] 10 | 11 | include::jsonp003.adoc[] 12 | 13 | include::jsonp004.adoc[] 14 | 15 | include::jsonp005.adoc[] 16 | 17 | include::jsonp006.adoc[] 18 | 19 | include::jsonp007.adoc[] 20 | 21 | include::jsonp008.adoc[] 22 | -------------------------------------------------------------------------------- /src/main/asciidoc/jsonp/jsonp005.adoc: -------------------------------------------------------------------------------- 1 | == JSON in Jakarta EE RESTful Web Services 2 | 3 | This section explains how the Jakarta JSON Processing is related to other Jakarta EE packages that provide JSON support for RESTful web services. 4 | See xref:building-restful-web-services-with-jakarta-rest[xrefstyle=full] for more information on RESTful web services. 5 | 6 | Jersey, the Jakarta RESTful Web Services implementation included in GlassFish Server, provides support for binding JSON data from RESTful resource methods to Java objects using Jakarta XML Binding, as described in <> in xref:jakarta-rest-advanced-topics-and-an-example[xrefstyle=full]. 7 | However, JSON support is not part of Jakarta RESTful Web Services or Jakarta XML Binding, so that procedure may not work for Jakarta EE implementations other than GlassFish Server. 8 | 9 | You can still use the Jakarta JSON Processing with Jakarta RESTful Web Services resource methods. 10 | For more information, see the sample code for JSON Processing included with the Jakarta EE tutorial examples. 11 | -------------------------------------------------------------------------------- /src/main/asciidoc/jsonp/jsonp008.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about the Jakarta JSON Processing 2 | 3 | For more information on JSON processing in Jakarta EE, see the Jakarta JSON Processing specification: 4 | 5 | https://jakarta.ee/specifications/jsonp/2.0/[^] 6 | -------------------------------------------------------------------------------- /src/main/asciidoc/overview/overview.adoc: -------------------------------------------------------------------------------- 1 | = Overview 2 | 3 | This chapter introduces you to Jakarta EE enterprise application development. 4 | Here you will review development basics, learn about the Jakarta EE architecture and APIs, become acquainted with important terms and concepts, and find out how to approach Jakarta EE application programming, assembly, and deployment. 5 | 6 | include::overview001.adoc[] 7 | 8 | include::overview002.adoc[] 9 | 10 | include::overview003.adoc[] 11 | 12 | include::overview004.adoc[] 13 | 14 | include::overview005.adoc[] 15 | 16 | include::overview006.adoc[] 17 | 18 | include::overview007.adoc[] 19 | 20 | include::overview008.adoc[] 21 | 22 | include::overview009.adoc[] 23 | 24 | include::overview010.adoc[] 25 | -------------------------------------------------------------------------------- /src/main/asciidoc/overview/overview002.adoc: -------------------------------------------------------------------------------- 1 | == Jakarta EE 9 Platform Highlights 2 | 3 | The goal of the Jakarta EE 9 release is to deliver a set of specifications functionally similar to Jakarta EE 8 but in the new Jakarta EE 9 namespace jakarta.*. 4 | 5 | In addition, the Jakarta EE 9 release removes a small set of specifications from Jakarta EE 8 that were old, optional, or deprecated in order to reduce the surface area of the APIs to ensure that it is easier for new vendors to enter the ecosystem – as well as reduce the burden on implementation, migration, and maintenance of these old APIs. 6 | 7 | The following Jakarta EE Technologies were removed from the Jakarta EE Platform: 8 | 9 | * XML Registries 1.0 10 | 11 | * XML RPC 1.1 12 | 13 | * Deployment 1.7 14 | 15 | * Management 1.1 16 | 17 | * Distributed Interoperability (EJB 3.2 Core Specification, Chapter 10) 18 | 19 | Aside from the removed technologies, some technologies in Jakarta EE 9 release are marked as optional. 20 | The reason for this is that some of the technologies originally included in Jakarta EE are no longer as relevant as they were when they were introduced to the platform. 21 | 22 | Platform Specification Project can decide to officially "remove" the "optional" feature from the Platform in the next (or beyond) releases. 23 | 24 | The following technologies are optional: 25 | 26 | * Jakarta Enterprise Beans 3.2 and earlier entity beans and associated Jakarta Enterprise Beans QL 27 | 28 | * Jakarta Enterprise Beans 2.x API group 29 | 30 | * Jakarta Enterprise Web Services 2.0 31 | 32 | * Jakarta SOAP with Attachments 2.0 33 | 34 | * Jakarta Web Services Metadata 3.0 35 | 36 | * Jakarta XML Web Services 3.0 37 | 38 | * Jakarta XML Binding 3.0 39 | -------------------------------------------------------------------------------- /src/main/asciidoc/overview/overview003.adoc: -------------------------------------------------------------------------------- 1 | == Jakarta EE Application Model 2 | 3 | The Jakarta EE application model begins with the Java programming language and the Java virtual machine. 4 | The proven portability, security, and developer productivity they provide form the basis of the application model. 5 | Jakarta EE is designed to support applications that implement enterprise services for customers, employees, suppliers, partners, and others who make demands on or contributions to the enterprise. 6 | Such applications are inherently complex, potentially accessing data from a variety of sources and distributing applications to a variety of clients. 7 | 8 | To better control and manage these applications, the business functions to support these various users are conducted in the middle tier. 9 | The middle tier represents an environment that is closely controlled by an enterprise's information technology department. 10 | The middle tier is typically run on dedicated server hardware and has access to the full services of the enterprise. 11 | 12 | The Jakarta EE application model defines an architecture for implementing services as multitier applications that deliver the scalability, accessibility, and manageability needed by enterprise-level applications. 13 | This model partitions the work needed to implement a multitier service into the following parts: 14 | 15 | * The business and presentation logic to be implemented by the developer 16 | 17 | * The standard system services provided by the Jakarta EE platform 18 | 19 | The developer can rely on the platform to provide solutions for the hard systems-level problems of developing a multitier service. 20 | -------------------------------------------------------------------------------- /src/main/asciidoc/overview/overview007.adoc: -------------------------------------------------------------------------------- 1 | == Jakarta EE Application Assembly and Deployment 2 | 3 | A Jakarta EE application is packaged into one or more standard units for deployment to any Jakarta EE platform-compliant system. 4 | Each unit contains 5 | 6 | * A functional component or components, such as an enterprise bean, web page, servlet, or applet 7 | 8 | * An optional deployment descriptor that describes its content 9 | 10 | Once a Jakarta EE unit has been produced, it is ready to be deployed. 11 | Deployment typically involves using a platform's deployment tool to specify location-specific information, such as a list of local users who can access it and the name of the local database. 12 | Once deployed on a local platform, the application is ready to run. 13 | -------------------------------------------------------------------------------- /src/main/asciidoc/packaging/packaging.adoc: -------------------------------------------------------------------------------- 1 | = Packaging 2 | 3 | This chapter describes packaging. 4 | A Jakarta EE application is packaged into one or more standard units for deployment to any Jakarta EE platform-compliant system. 5 | Each unit contains a functional component or components, such as an enterprise bean, web page, servlet, or applet, and an optional deployment descriptor that describes its content. 6 | 7 | include::packaging001.adoc[] 8 | 9 | include::packaging002.adoc[] 10 | 11 | include::packaging003.adoc[] 12 | 13 | include::packaging004.adoc[] 14 | -------------------------------------------------------------------------------- /src/main/asciidoc/packaging/packaging004.adoc: -------------------------------------------------------------------------------- 1 | == Packaging Resource Adapter Archives 2 | 3 | A Resource Adapter Archive (RAR) file stores XML files, Java classes, and other objects for Jakarta EE Connector applications. 4 | A resource adapter can be deployed on any Jakarta EE server, much like a Jakarta EE application. 5 | A RAR file can be contained in an Enterprise Archive (EAR) file, or it can exist as a separate file. 6 | 7 | The RAR file contains 8 | 9 | * A JAR file with the implementation classes of the resource adapter 10 | 11 | * An optional `META-INF/` directory that can store an `ra.xml` file and/or an application server–specific deployment descriptor used for configuration purposes 12 | 13 | A RAR file can be deployed on the application server as a standalone component or as part of a larger application. 14 | In both cases, the adapter is available to all applications using a lookup procedure. 15 | -------------------------------------------------------------------------------- /src/main/asciidoc/partbeanvalidation.adoc: -------------------------------------------------------------------------------- 1 | = Bean Validation 2 | 3 | Part IV explores Jakarta Bean Validation. 4 | 5 | :leveloffset: +1 6 | 7 | include::bean-validation/bean-validation.adoc[] 8 | 9 | include::bean-validation-advanced/bean-validation-advanced.adoc[] 10 | 11 | :leveloffset: -1 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/partcasestudies.adoc: -------------------------------------------------------------------------------- 1 | = Case Studies 2 | 3 | Part XII presents case studies that use a variety of Jakarta EE technologies. 4 | 5 | :leveloffset: +1 6 | 7 | include::dukes-bookstore/dukes-bookstore.adoc[] 8 | 9 | include::dukes-tutoring/dukes-tutoring.adoc[] 10 | 11 | include::dukes-forest/dukes-forest.adoc[] 12 | 13 | :leveloffset: -1 14 | -------------------------------------------------------------------------------- /src/main/asciidoc/partcdi.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta EE Contexts and Dependency Injection 2 | 3 | Part V explores Jakarta EE Contexts and Dependency Injection (CDI). 4 | 5 | :leveloffset: +1 6 | 7 | include::cdi-basic/cdi-basic.adoc[] 8 | 9 | include::cdi-basicexamples/cdi-basicexamples.adoc[] 10 | 11 | include::cdi-adv/cdi-adv.adoc[] 12 | 13 | include::cdi-bootstrap-se8/cdi-bootstrap-se8.adoc[] 14 | 15 | include::cdi-adv-examples/cdi-adv-examples.adoc[] 16 | 17 | :leveloffset: -1 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/partentbeans.adoc: -------------------------------------------------------------------------------- 1 | = Enterprise Beans 2 | 3 | Part VII explores Jakarta Enterprise Beans components. 4 | 5 | :leveloffset: +1 6 | 7 | include::ejb-intro/ejb-intro.adoc[] 8 | 9 | include::ejb-gettingstarted/ejb-gettingstarted.adoc[] 10 | 11 | include::ejb-basicexamples/ejb-basicexamples.adoc[] 12 | 13 | include::ejb-embedded/ejb-embedded.adoc[] 14 | 15 | include::ejb-async/ejb-async.adoc[] 16 | 17 | :leveloffset: -1 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/partintro.adoc: -------------------------------------------------------------------------------- 1 | = Introduction 2 | 3 | Part I introduces the platform, the tutorial, and the examples. 4 | 5 | :leveloffset: +1 6 | 7 | include::overview/overview.adoc[] 8 | 9 | include::usingexamples/usingexamples.adoc[] 10 | 11 | :leveloffset: -1 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/partmessaging.adoc: -------------------------------------------------------------------------------- 1 | = Messaging 2 | 3 | Part IX introduces messaging. 4 | 5 | :leveloffset: +1 6 | 7 | include::jms-concepts/jms-concepts.adoc[] 8 | 9 | include::jms-examples/jms-examples.adoc[] 10 | 11 | :leveloffset: -1 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/partpersist.adoc: -------------------------------------------------------------------------------- 1 | = Persistence 2 | 3 | Part VIII explores Jakarta Persistence. 4 | 5 | :leveloffset: +1 6 | 7 | include::persistence-intro/persistence-intro.adoc[] 8 | 9 | include::persistence-basicexamples/persistence-basicexamples.adoc[] 10 | 11 | include::persistence-querylanguage/persistence-querylanguage.adoc[] 12 | 13 | include::persistence-criteria/persistence-criteria.adoc[] 14 | 15 | include::persistence-string-queries/persistence-string-queries.adoc[] 16 | 17 | include::persistence-locking/persistence-locking.adoc[] 18 | 19 | include::persistence-entitygraphs/persistence-entitygraphs.adoc[] 20 | 21 | include::persistence-cache/persistence-cache.adoc[] 22 | 23 | :leveloffset: -1 24 | -------------------------------------------------------------------------------- /src/main/asciidoc/partplatform.adoc: -------------------------------------------------------------------------------- 1 | = Platform Basics 2 | 3 | Part II introduces platform basics. 4 | 5 | :leveloffset: +1 6 | 7 | include::resource-creation/resource-creation.adoc[] 8 | 9 | include::injection/injection.adoc[] 10 | 11 | include::packaging/packaging.adoc[] 12 | 13 | :leveloffset: -1 14 | -------------------------------------------------------------------------------- /src/main/asciidoc/partsecurity.adoc: -------------------------------------------------------------------------------- 1 | = Security 2 | 3 | Part X explores security concepts and examples. 4 | 5 | :leveloffset: +1 6 | 7 | include::security-intro/security-intro.adoc[] 8 | 9 | include::security-webtier/security-webtier.adoc[] 10 | 11 | include::security-jakartaee/security-jakartaee.adoc[] 12 | 13 | include::security-api/security-api.adoc[] 14 | 15 | include::security-advanced/security-advanced.adoc[] 16 | 17 | :leveloffset: -1 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/partsupporttechs.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta EE Supporting Technologies 2 | 3 | Part XI explores several technologies that support the Jakarta EE 4 | platform. 5 | 6 | :leveloffset: +1 7 | 8 | include::transactions/transactions.adoc[] 9 | 10 | include::resources/resources.adoc[] 11 | 12 | include::connectorexample/connectorexample.adoc[] 13 | 14 | include::interceptors/interceptors.adoc[] 15 | 16 | include::batch-processing/batch-processing.adoc[] 17 | 18 | include::concurrency-utilities/concurrency-utilities.adoc[] 19 | 20 | :leveloffset: -1 21 | -------------------------------------------------------------------------------- /src/main/asciidoc/partwebsvcs.adoc: -------------------------------------------------------------------------------- 1 | = Web Services 2 | 3 | Part VI explores web services. 4 | 5 | :leveloffset: +1 6 | 7 | include::webservices-intro/webservices-intro.adoc[] 8 | 9 | include::jaxws/jaxws.adoc[] 10 | 11 | include::jaxrs/jaxrs.adoc[] 12 | 13 | include::jaxrs-client/jaxrs-client.adoc[] 14 | 15 | include::jaxrs-advanced/jaxrs-advanced.adoc[] 16 | 17 | :leveloffset: -1 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/partwebtier.adoc: -------------------------------------------------------------------------------- 1 | = The Web Tier 2 | 3 | Part III explores the technologies in the web tier. 4 | 5 | :leveloffset: +1 6 | 7 | include::webapp/webapp.adoc[] 8 | 9 | include::faces-intro/faces-intro.adoc[] 10 | 11 | include::faces-facelets/faces-facelets.adoc[] 12 | 13 | include::faces-el/faces-el.adoc[] 14 | 15 | include::faces-page/faces-page.adoc[] 16 | 17 | include::faces-page-core/faces-page-core.adoc[] 18 | 19 | include::faces-develop/faces-develop.adoc[] 20 | 21 | include::faces-ajax/faces-ajax.adoc[] 22 | 23 | include::faces-advanced-cc/faces-advanced-cc.adoc[] 24 | 25 | include::faces-custom/faces-custom.adoc[] 26 | 27 | include::faces-configure/faces-configure.adoc[] 28 | 29 | include::faces-ws/faces-ws.adoc[] 30 | 31 | include::servlets/servlets.adoc[] 32 | 33 | include::websocket/websocket.adoc[] 34 | 35 | include::jsonp/jsonp.adoc[] 36 | 37 | include::jsonb/jsonb.adoc[] 38 | 39 | include::webi18n/webi18n.adoc[] 40 | 41 | :leveloffset: -1 42 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-basicexamples/persistence-basicexamples.adoc: -------------------------------------------------------------------------------- 1 | = Running the Persistence Examples 2 | 3 | This chapter explains how to use Jakarta Persistence. 4 | The material here focuses on the source code and settings of three examples. 5 | 6 | include::persistence-basicexamples001.adoc[] 7 | 8 | include::persistence-basicexamples002.adoc[] 9 | 10 | include::persistence-basicexamples003.adoc[] 11 | 12 | include::persistence-basicexamples004.adoc[] 13 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-basicexamples/persistence-basicexamples001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of the Persistence Examples 2 | 3 | The first example, `order`, is an application that uses a stateful session bean to manage entities related to an ordering system. 4 | The second example, `roster`, is an application that manages a community sports system. 5 | The third example, `address-book`, is a web application that stores contact data. 6 | This chapter assumes that you are familiar with the concepts detailed in <>. 7 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-cache/persistence-cache.adoc: -------------------------------------------------------------------------------- 1 | = Using a Second-Level Cache with Jakarta Persistence Applications 2 | 3 | This chapter explains how to modify the second-level cache mode settings to improve the performance of applications that use the Jakarta Persistence. 4 | 5 | include::persistence-cache001.adoc[] 6 | 7 | include::persistence-cache002.adoc[] 8 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-criteria/persistence-criteria.adoc: -------------------------------------------------------------------------------- 1 | = Using the Criteria API to Create Queries 2 | 3 | The Criteria API is used to define queries for entities and their persistent state by creating query-defining objects. 4 | Criteria queries are written using Java programming language APIs, are typesafe, and are portable. 5 | Such queries work regardless of the underlying data store. 6 | 7 | include::persistence-criteria001.adoc[] 8 | 9 | include::persistence-criteria002.adoc[] 10 | 11 | include::persistence-criteria003.adoc[] 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs.adoc: -------------------------------------------------------------------------------- 1 | = Creating Fetch Plans with Entity Graphs 2 | 3 | This chapter explains how to use entity graphs to create fetch plans for Jakarta Persistence operations and queries. 4 | 5 | include::persistence-entitygraphs001.adoc[] 6 | 7 | include::persistence-entitygraphs002.adoc[] 8 | 9 | include::persistence-entitygraphs003.adoc[] 10 | 11 | include::persistence-entitygraphs004.adoc[] 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of Using Fetch Plans and Entity Graphs 2 | 3 | Entity graphs are templates for a particular Persistence query or operation. 4 | They are used when creating fetch plans, or groups of persistent fields that are retrieved at the same time. 5 | Application developers use fetch plans to group together related persistent fields to improve runtime performance. 6 | 7 | By default, entity fields or properties are fetched lazily. 8 | Developers specify fields or properties as part of a fetch plan, and the persistence provider will fetch them eagerly. 9 | 10 | For example, an email application that stores messages as `EmailMessage` entities prioritizes fetching some fields over others. 11 | The sender, subject, and date will be viewed the most often, in mailbox views and when the message is displayed. 12 | The `EmailMessage` entity has a collection of related `EmailAttachment` entities. 13 | For performance reasons the attachments should not be fetched until they are needed, but the file names of the attachment are important. 14 | A developer working on this application might make a fetch plan that eagerly fetches the important fields from `EmailMessage` and `EmailAttachment` while fetching the lower priority data lazily. 15 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs004.adoc: -------------------------------------------------------------------------------- 1 | == Using Entity Graphs in Query Operations 2 | 3 | To specify entity graphs for both typed and untyped queries, call the `setHint` method on the query object and specify either `jakarta.persistence.loadgraph` or `jakarta.persistence.fetchgraph` as the property name and an `EntityGraph` instance as the value: 4 | 5 | [source,java] 6 | ---- 7 | EntityGraph eg = em.getEntityGraph("previewEmailEntityGraph"); 8 | List messages = em.createNamedQuery("findAllEmailMessages") 9 | .setParameter("mailbox", "inbox") 10 | .setHint("jakarta.persistence.loadgraph", eg) 11 | .getResultList(); 12 | ---- 13 | 14 | In this example, the `previewEmailEntityGraph` is used for the `findAllEmailMessages` named query. 15 | 16 | Typed queries use the same technique: 17 | 18 | [source,java] 19 | ---- 20 | EntityGraph eg = em.getEntityGraph("previewEmailEntityGraph"); 21 | 22 | CriteriaQuery cq = cb.createQuery(EmailMessage.class); 23 | Root message = cq.from(EmailMessage.class); 24 | TypedQuery q = em.createQuery(cq); 25 | q.setHint("jakarta.persistence.loadgraph", eg); 26 | List messages = q.getResultList(); 27 | ---- 28 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-intro/persistence-intro.adoc: -------------------------------------------------------------------------------- 1 | = Introduction to Jakarta Persistence 2 | 3 | This chapter provides a description of Jakarta Persistence. 4 | 5 | include::persistence-intro001.adoc[] 6 | 7 | include::persistence-intro002.adoc[] 8 | 9 | include::persistence-intro003.adoc[] 10 | 11 | include::persistence-intro004.adoc[] 12 | 13 | include::persistence-intro005.adoc[] 14 | 15 | include::persistence-intro006.adoc[] 16 | 17 | include::persistence-intro007.adoc[] 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-intro/persistence-intro001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of Jakarta Persistence 2 | 3 | Jakarta Persistence provides Java developers with an object/relational mapping facility for managing relational data in Java applications. 4 | Jakarta Persistence consists of four areas: 5 | 6 | * Jakarta Persistence 7 | 8 | * The query language 9 | 10 | * The Jakarta Persistence Criteria API 11 | 12 | * Object/relational mapping metadata 13 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-intro/persistence-intro005.adoc: -------------------------------------------------------------------------------- 1 | == Querying Entities 2 | 3 | Jakarta Persistence provides the following methods for querying entities. 4 | 5 | * The Jakarta Persistence query language (JPQL) is a simple, string-based language similar to SQL used to query entities and their relationships. 6 | See xref:the-jakarta-persistence-query-language[xrefstyle=full] for more information. 7 | 8 | * The Criteria API is used to create typesafe queries using Java programming language APIs to query for entities and their relationships. 9 | See xref:using-the-criteria-api-to-create-queries[xrefstyle=full] for more information. 10 | 11 | Both JPQL and the Criteria API have advantages and disadvantages. 12 | 13 | Just a few lines long, JPQL queries are typically more concise and more readable than Criteria queries. 14 | Developers familiar with SQL will find it easy to learn the syntax of JPQL. 15 | JPQL named queries can be defined in the entity class using a Java programming language annotation or in the application's deployment descriptor. 16 | JPQL queries are not typesafe, however, and require a cast when retrieving the query result from the entity manager. 17 | This means that type-casting errors may not be caught at compile time. 18 | JPQL queries don't support open-ended parameters. 19 | 20 | Criteria queries allow you to define the query in the business tier of the application. 21 | Although this is also possible using JPQL dynamic queries, Criteria queries provide better performance because JPQL dynamic queries must be parsed each time they are called. 22 | Criteria queries are typesafe and therefore don't require casting, as JPQL queries do. 23 | The Criteria API is just another Java programming language API and doesn't require developers to learn the syntax of another query language. 24 | Criteria queries are typically more verbose than JPQL queries and require the developer to create several objects and perform operations on those objects before submitting the query to the entity manager. 25 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-intro/persistence-intro007.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Persistence 2 | 3 | For more information about Jakarta Persistence, see 4 | 5 | * Jakarta Persistence 3.0 API specification: + 6 | https://jakarta.ee/specifications/persistence/3.0/[^] 7 | 8 | * EclipseLink, the Jakarta Persistence implementation in GlassFish Server: + 9 | https://www.eclipse.org/eclipselink/[^] 10 | 11 | * EclipseLink wiki documentation: + 12 | https://wiki.eclipse.org/EclipseLink[^] 13 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-locking/persistence-locking.adoc: -------------------------------------------------------------------------------- 1 | = Controlling Concurrent Access to Entity Data with Locking 2 | 3 | This chapter details how to handle concurrent access to entity data, and the locking strategies available to Jakarta Persistence application developers. 4 | 5 | include::persistence-locking001.adoc[] 6 | 7 | include::persistence-locking002.adoc[] 8 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-querylanguage/persistence-querylanguage.adoc: -------------------------------------------------------------------------------- 1 | = The Jakarta Persistence Query Language 2 | 3 | This chapter describes the Jakarta Persistence query language that defines queries for entities and their persistent state. 4 | The query language allows you to write portable queries that work regardless of the underlying data store. 5 | 6 | include::persistence-querylanguage001.adoc[] 7 | 8 | include::persistence-querylanguage002.adoc[] 9 | 10 | include::persistence-querylanguage003.adoc[] 11 | 12 | include::persistence-querylanguage004.adoc[] 13 | 14 | include::persistence-querylanguage005.adoc[] 15 | 16 | include::persistence-querylanguage006.adoc[] 17 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-querylanguage/persistence-querylanguage001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of the Jakarta Persistence Query Language 2 | 3 | The query language uses the abstract persistence schemas of entities, including their relationships, for its data model and defines operators and expressions based on this data model. 4 | The scope of a query spans the abstract schemas of related entities that are packaged in the same persistence unit. 5 | The query language uses an SQL-like syntax to select objects or values based on entity abstract schema types and relationships among them. 6 | 7 | This chapter relies on the material presented in earlier chapters. 8 | For conceptual information, see xref:introduction-to-jakarta-persistence[xrefstyle=full]. 9 | For code examples, see xref:running-the-persistence-examples[xrefstyle=full]. 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-querylanguage/persistence-querylanguage002.adoc: -------------------------------------------------------------------------------- 1 | == Query Language Terminology 2 | 3 | The following list defines some of the terms referred to in this chapter. 4 | 5 | * Abstract schema: The persistent schema abstraction (persistent entities, their state, and their relationships) over which queries operate. 6 | The query language translates queries over this persistent schema abstraction into queries that are executed over the database schema to which entities are mapped. 7 | 8 | * Abstract schema type: The type to which the persistent property of an entity evaluates in the abstract schema. 9 | That is, each persistent field or property in an entity has a corresponding state field of the same type in the abstract schema. 10 | The abstract schema type of an entity is derived from the entity class and the metadata information provided by Java language annotations. 11 | 12 | * Backus-Naur Form (BNF): A notation that describes the syntax of high-level languages. 13 | The syntax diagrams in this chapter are in BNF notation. 14 | 15 | * Navigation: The traversal of relationships in a query language expression. 16 | The navigation operator is a period. 17 | 18 | * Path expression: An expression that navigates to an entity's state or relationship field. 19 | 20 | * State field: A persistent field of an entity. 21 | 22 | * Relationship field: A persistent field of an entity whose type is the abstract schema type of the related entity. 23 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-string-queries/persistence-string-queries.adoc: -------------------------------------------------------------------------------- 1 | = Creating and Using String-Based Criteria Queries 2 | 3 | This chapter describes how to create weakly typed string-based Criteria API queries. 4 | 5 | include::persistence-string-queries001.adoc[] 6 | 7 | include::persistence-string-queries002.adoc[] 8 | 9 | include::persistence-string-queries003.adoc[] 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-string-queries/persistence-string-queries001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of String-Based Criteria API Queries 2 | 3 | String-based Criteria API queries ("string-based queries") are Java programming language queries that use strings rather than strongly typed metamodel objects to specify entity attributes when traversing a data hierarchy. 4 | String-based queries are constructed similarly to metamodel queries, can be static or dynamic, and can express the same kind of queries and operations as strongly typed metamodel queries. 5 | 6 | Strongly typed metamodel queries are the preferred method of constructing Criteria API queries. 7 | 8 | The main advantage of string-based queries over metamodel queries is the ability to construct Criteria queries at development time without the need to generate static metamodel classes or otherwise access dynamically generated metamodel classes. 9 | 10 | The main disadvantage to string-based queries is their lack of type safety; this problem may lead to runtime errors due to type mismatches that would be caught at development time if you used strongly typed metamodel queries. 11 | 12 | For information on constructing criteria queries, see xref:using-the-criteria-api-to-create-queries[xrefstyle=full]. 13 | -------------------------------------------------------------------------------- /src/main/asciidoc/persistence-string-queries/persistence-string-queries003.adoc: -------------------------------------------------------------------------------- 1 | == Executing String-Based Queries 2 | 3 | String-based queries are executed similarly to strongly typed Criteria queries. 4 | First create a `jakarta.persistence.TypedQuery` object by passing the criteria query object to the `EntityManager.createQuery` method, then call either `getSingleResult` or `getResultList` on the query object to execute the query: 5 | 6 | [source,java] 7 | ---- 8 | CriteriaQuery cq = cb.createQuery(Pet.class); 9 | Root pet = cq.from(Pet.class); 10 | cq.where(cb.equal(pet.get("name"), "Fido")); 11 | TypedQuery q = em.createQuery(cq); 12 | List results = q.getResultList(); 13 | ---- 14 | -------------------------------------------------------------------------------- /src/main/asciidoc/resource-creation/resource-creation.adoc: -------------------------------------------------------------------------------- 1 | = Resource Creation 2 | 3 | A resource is a program object that provides connections to such systems as database servers and messaging systems. 4 | Jakarta EE components can access a wide variety of resources, including databases, mail sessions, Jakarta Messaging objects, and URLs. 5 | The Jakarta EE platform provides mechanisms that allow you to access all these resources in a similar manner. 6 | This chapter examines several types of resources and explains how to create them. 7 | 8 | include::resource-creation001.adoc[] 9 | 10 | include::resource-creation002.adoc[] 11 | 12 | include::resource-creation003.adoc[] 13 | -------------------------------------------------------------------------------- /src/main/asciidoc/resource-creation/resource-creation001.adoc: -------------------------------------------------------------------------------- 1 | == Resources and JNDI Naming 2 | 3 | In a distributed application, components need to access other components and resources, such as databases. 4 | For example, a servlet might invoke remote methods on an enterprise bean that retrieves information from a database. 5 | In the Jakarta EE platform, the Java Naming and Directory Interface (JNDI) naming service enables components to locate other components and resources. 6 | 7 | A resource is a program object that provides connections to systems, such as database servers and messaging systems. 8 | A Java Database Connectivity resource is sometimes referred to as a data source. 9 | Each resource object is identified by a unique, people-friendly name, called the JNDI name. 10 | For example, the JNDI name of the preconfigured JDBC resource for Apache Derby shipped with GlassFish Server is `java:comp/DefaultDataSource`. 11 | 12 | An administrator creates resources in a JNDI namespace. 13 | In GlassFish Server, you can use either the Administration Console or the `asadmin` command to create resources. 14 | Applications then use annotations to inject the resources. 15 | If an application uses resource injection, GlassFish Server invokes the JNDI API, and the application is not required to do so. 16 | However, it is also possible for an application to locate resources by making direct calls to the JNDI API. 17 | 18 | A resource object and its JNDI name are bound together by the naming and directory service. 19 | To create a new resource, a new name/object binding is entered into the JNDI namespace. 20 | You inject resources by using the `@Resource` annotation in an application. 21 | 22 | You can use a deployment descriptor to override the resource mapping that you specify in an annotation. 23 | Using a deployment descriptor allows you to change an application by repackaging it rather than by both recompiling the source files and repackaging. 24 | However, for most applications a deployment descriptor is not necessary. 25 | -------------------------------------------------------------------------------- /src/main/asciidoc/resource-creation/resource-creation003.adoc: -------------------------------------------------------------------------------- 1 | == Creating Resources Administratively 2 | 3 | Before you deploy or run many applications, you may need to create resources for them. 4 | An application can include a `glassfish-resources.xml` file that can be used to define resources for that application and others. 5 | You can then use the `asadmin` command, specifying as the argument a file named `glassfish-resources.xml`, to create the resources administratively, as shown here: 6 | 7 | [source,shell] 8 | ---- 9 | asadmin add-resources glassfish-resources.xml 10 | ---- 11 | 12 | The `glassfish-resources.xml` file can be created in any project using NetBeans IDE or by hand. 13 | Some of the Jakarta Messaging examples use this approach to resource creation. 14 | A file for creating the resources needed for the Messaging simple producer example can be found in the `jms/simple/producer/src/main/setup` directory. 15 | 16 | You could also use the `asadmin create-jms-resource` command to create the resources for this example. 17 | When you are done using the resources, you would use the `asadmin list-jms-resources` command to display their names, and the `asadmin delete-jms-resource` command to remove them, regardless of the way you created the resources. 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/resources/resources.adoc: -------------------------------------------------------------------------------- 1 | = Resource Adapters and Contracts 2 | 3 | This chapter examines resource adapters and explains how communications between Jakarta EE servers and EIS systems are mediated by them. 4 | 5 | include::resources001.adoc[] 6 | 7 | include::resources002.adoc[] 8 | 9 | include::resources003.adoc[] 10 | 11 | include::resources004.adoc[] 12 | 13 | include::resources005.adoc[] 14 | -------------------------------------------------------------------------------- /src/main/asciidoc/resources/resources004.adoc: -------------------------------------------------------------------------------- 1 | == Using Resource Adapters with Jakarta Contexts and Dependency Injection (CDI) 2 | 3 | For details about CDI, see xref:introduction-to-jakarta-contexts-and-dependency-injection[xrefstyle=full] and xref:jakarta-contexts-and-dependency-injection-advanced-topics[xrefstyle=full]. 4 | 5 | Do not specify the following classes in the resource adapter as CDI managed beans (that is, do not inject them), because the behavior of these classes as CDI managed beans has not been portably defined. 6 | 7 | * Resource adapter beans: These beans are classes that are annotated with the `jakarta.resource.spi.Connector` annotation or are declared as corresponding elements in the resource adapter deployment descriptor, `ra.xml`. 8 | 9 | * Managed connection factory beans: These beans are classes that are annotated with the `jakarta.resource.spi.ConnectorDefinition` annotation or the `jakarta.resource.spi.ConnectorDefinitions` annotation or are declared as corresponding elements in `ra.xml`. 10 | 11 | * Activation specification beans: These beans are classes that are annotated with the `jakarta.resource.spi.Activation` annotation or are declared as corresponding elements in `ra.xml`. 12 | 13 | * Administered object beans: These beans are classes that are annotated with the `jakarta.resource.spi.AdministeredObject` annotation or are declared as corresponding elements in `ra.xml`. 14 | 15 | Other types of classes in the resource adapter can be CDI managed beans and will behave in a portable manner. 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/resources/resources005.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Resource Adapters 2 | 3 | For more information about resource adapters and annotations, see 4 | 5 | * Jakarta EE 9 Platform Specification: + 6 | https://jakarta.ee/specifications/platform/[^] 7 | 8 | * Jakarta Connectors 2.0 specification: + 9 | https://jakarta.ee/specifications/connectors/2.0/[^] 10 | 11 | * Jakarta Enterprise Beans specification: + 12 | https://jakarta.ee/specifications/enterprise-beans/4.0/[^] 13 | 14 | * Jakarta Annotations: + 15 | https://jakarta.ee/specifications/annotations/2.0/[^] 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/security-advanced/security-advanced.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta EE Security: Advanced Topics 2 | 3 | This chapter provides advanced information on securing Jakarta EE applications. 4 | 5 | include::security-advanced001.adoc[] 6 | 7 | include::security-advanced002.adoc[] 8 | 9 | include::security-advanced003.adoc[] 10 | 11 | include::security-advanced004.adoc[] 12 | 13 | include::security-advanced005.adoc[] 14 | 15 | include::security-advanced006.adoc[] 16 | 17 | include::security-advanced007.adoc[] 18 | 19 | include::security-advanced008.adoc[] 20 | -------------------------------------------------------------------------------- /src/main/asciidoc/security-advanced/security-advanced008.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Advanced Security Topics 2 | 3 | For more information about the security topics covered in this chapter, see 4 | 5 | * Documentation on the `keytool` command: + 6 | https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html[^] 7 | 8 | * Java Authentication and Authorization Service (JAAS) Reference Guide: + 9 | https://docs.oracle.com/javase/8/docs/technotes/guides/security/jaas/JAASRefGuide.html[^] 10 | 11 | * Java Authentication and Authorization Service (JAAS): LoginModule Developer's Guide: + 12 | https://docs.oracle.com/javase/8/docs/technotes/guides/security/jaas/JAASLMDevGuide.html[^] 13 | 14 | * Documentation on security policy file syntax: + 15 | https://docs.oracle.com/javase/8/docs/technotes/guides/security/PolicyFiles.html#FileSyntax[^] 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/security-api/security-api.adoc: -------------------------------------------------------------------------------- 1 | = Using Jakarta Security 2 | 3 | This chapter describes the authentication and credential validation functionality provided by Jakarta Security. 4 | The API also defines a `SecurityContext` access point for programmatic security. 5 | 6 | include::security-api001.adoc[] 7 | 8 | include::security-api002.adoc[] 9 | 10 | include::security-api003.adoc[] 11 | 12 | include::security-api004.adoc[] 13 | 14 | include::security-api005.adoc[] 15 | -------------------------------------------------------------------------------- /src/main/asciidoc/security-intro/security-intro.adoc: -------------------------------------------------------------------------------- 1 | = Introduction to Security in the Jakarta EE Platform 2 | 3 | This chapter introduces basic security concepts and security mechanisms. 4 | More information on these concepts and mechanisms can be found in the chapter on security in the Jakarta EE 9 specification. 5 | 6 | include::security-intro001.adoc[] 7 | 8 | include::security-intro002.adoc[] 9 | 10 | include::security-intro003a.adoc[] 11 | 12 | include::security-intro003.adoc[] 13 | 14 | include::security-intro004.adoc[] 15 | 16 | include::security-intro005a.adoc[] 17 | 18 | include::security-intro005.adoc[] 19 | 20 | include::security-intro006.adoc[] 21 | 22 | include::security-intro007.adoc[] 23 | -------------------------------------------------------------------------------- /src/main/asciidoc/security-intro/security-intro004.adoc: -------------------------------------------------------------------------------- 1 | == Securing GlassFish Server 2 | 3 | This tutorial describes deployment to GlassFish Server, which provides highly secure, interoperable, and distributed component computing based on the Jakarta EE security model. 4 | GlassFish Server supports the Jakarta EE 9 security model. 5 | You can configure GlassFish Server for the following purposes. 6 | 7 | * Adding, deleting, or modifying authorized users. 8 | For more information on this topic, see <>. 9 | 10 | * Configuring secure HTTP and Internet Inter-Orb Protocol (IIOP) listeners. 11 | 12 | * Configuring secure Java Management Extensions (JMX) connectors. 13 | 14 | * Adding, deleting, or modifying existing or custom realms. 15 | 16 | * Defining an interface for pluggable authorization providers using Jakarta Authorization. 17 | Jakarta Authorization defines security contracts between GlassFish Server and authorization policy modules. 18 | These contracts specify how the authorization providers are installed, configured, and used in access decisions. 19 | 20 | * Using pluggable audit modules. 21 | 22 | * Customizing authentication mechanisms. 23 | All implementations of Jakarta EE 9 compatible web containers are required to support the Servlet Profile of Jakarta Authentication, which offers an avenue for customizing the authentication mechanism applied by the web container on behalf of one or more applications. 24 | 25 | * Setting and changing policy permissions for an application. 26 | -------------------------------------------------------------------------------- /src/main/asciidoc/security-intro/security-intro005a.adoc: -------------------------------------------------------------------------------- 1 | == Working with Identity Stores 2 | 3 | An identity store is a database or directory (store) that contains identity information about a collection of users that includes an application's callers. 4 | An identity store holds callers names, group membership information, and information sufficient to allow it to validate a caller's credentials. 5 | An identity store may also contain other information, such as globally unique caller identifiers or other caller attributes. 6 | 7 | As specified in the Jakarta EE Security API, the `IdentityStore` interface provides an abstraction of an identity store. 8 | Implementations of the `IdentityStore` interface interact with identity stores to authenticate users and to retrieve caller group information. 9 | Most often, an implementation of the `IdentityStore` interface interacts with an external identity store, such as an LDAP server, but it can also manage user account data itself. 10 | 11 | The `IdentityStore` interface is intended primarily for use by the `HttpAuthenticationMechanism` (also specified in the Jakarta Security), but can be used by other implementations such as a JASPIC `ServerAuthModule` or a container's built-in authentication mechanisms. 12 | Using the `HttpAuthenticationMechanism` and `IdentityStore` implementations, both built-in and custom, provides a significant advantage over the BASIC and FORM mechanisms defined by Servlet 5.0 (and previous versions) and configured declaratively using `` in `web.xml`, because it allows an application to control the identity stores it will authenticate against in a standard, portable way. 13 | 14 | An application can provide its own `IdentityStore`, or use the built in LDAP or Database identity store implementations of the interface. 15 | For details about the `IdentityStore` interfaces and examples of their usage, see <>. 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/security-intro/security-intro007.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Security 2 | 3 | For more information about security in Jakarta EE applications, see 4 | 5 | * Jakarta EE 9 specification: + 6 | https://jakarta.ee/specifications/platform/9/[^] 7 | 8 | * Jakarta Security 2.0: + 9 | https://jakarta.ee/specifications/security/2.0/[^] 10 | 11 | * Jakarta Authentication 2.0: + 12 | https://jakarta.ee/specifications/authentication/2.0/[^] 13 | 14 | * Jakarta Enterprise Beans 4.0 specification: + 15 | https://jakarta.ee/specifications/enterprise-beans/4.0/[^] 16 | 17 | * Jakarta Enterprise Web Services 2.0 specification: + 18 | https://jakarta.ee/specifications/enterprise-ws/2.0/[^] 19 | 20 | * Java SE security information: + 21 | https://docs.oracle.com/javase/8/docs/technotes/guides/security/[^] 22 | 23 | * Jakarta Servlet 5.0 specification: + 24 | https://jakarta.ee/specifications/servlet/5.0/[^] 25 | 26 | * Jakarta Authorization 2.0 specification: + 27 | https://jakarta.ee/specifications/authorization/2.0/[^] 28 | -------------------------------------------------------------------------------- /src/main/asciidoc/security-jakartaee/security-jakartaee.adoc: -------------------------------------------------------------------------------- 1 | = Getting Started Securing Enterprise Applications 2 | 3 | This chapter describes how to administer security for enterprise applications. 4 | 5 | include::security-jakartaee001.adoc[] 6 | 7 | include::security-jakartaee002.adoc[] 8 | 9 | include::security-jakartaee003.adoc[] 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/security-jakartaee/security-jakartaee001.adoc: -------------------------------------------------------------------------------- 1 | == Basic Security Tasks for Enterprise Applications 2 | 3 | System administrators, application developers, bean providers, and deployers are responsible for administering security for enterprise applications. 4 | The basic security tasks are as follows: 5 | 6 | * Setting up a database of users and assigning them to the proper group 7 | 8 | * Setting up identity propagation 9 | 10 | * Setting GlassFish Server properties that enable the applications to run properly. 11 | Note that the the *Default Principal To Role Mapping* setting is enabled by default in the GlassFish Server Administration Console. 12 | 13 | * Annotating the classes and methods of an enterprise application to provide information about which methods need to have restricted access 14 | 15 | The sections on the security examples in this chapter and the previous chapter explain how to perform these tasks. 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/security-webtier/security-webtier.adoc: -------------------------------------------------------------------------------- 1 | = Getting Started Securing Web Applications 2 | 3 | This chapter describes in greater detail the ways to implement security for Jakarta EE web applications discussed in a general way in <>. The detail and examples in this chapter explore these security services as they relate to web components. 4 | 5 | include::security-webtier001.adoc[] 6 | 7 | include::security-webtier002.adoc[] 8 | 9 | include::security-webtier003.adoc[] 10 | 11 | include::security-webtier004.adoc[] 12 | -------------------------------------------------------------------------------- /src/main/asciidoc/servlets/servlets.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta Servlet Technology 2 | 3 | Jakarta Servlet technology provides dynamic, user-oriented content in web applications using a request-response programming model. 4 | 5 | include::servlets001.adoc[] 6 | 7 | include::servlets002.adoc[] 8 | 9 | include::servlets003.adoc[] 10 | 11 | include::servlets004.adoc[] 12 | 13 | include::servlets005.adoc[] 14 | 15 | include::servlets006.adoc[] 16 | 17 | include::servlets007.adoc[] 18 | 19 | include::servlets008.adoc[] 20 | 21 | include::servlets009.adoc[] 22 | 23 | include::servlets010.adoc[] 24 | 25 | include::servlets011.adoc[] 26 | 27 | include::servlets012.adoc[] 28 | 29 | include::servlets013.adoc[] 30 | 31 | include::servlets014a.adoc[] 32 | 33 | include::servlets014.adoc[] 34 | 35 | include::servlets014b.adoc[] 36 | 37 | include::servlets015.adoc[] 38 | 39 | include::servlets016.adoc[] 40 | 41 | include::servlets017.adoc[] 42 | 43 | include::servlets018.adoc[] 44 | -------------------------------------------------------------------------------- /src/main/asciidoc/servlets/servlets001.adoc: -------------------------------------------------------------------------------- 1 | == What Is a Servlet? 2 | 3 | A servlet is a Java programming language class used to extend the capabilities of servers that host applications accessed by means of a request-response programming model. 4 | Although servlets can respond to any type of request, they are commonly used to extend the applications hosted by web servers. 5 | For such applications, Jakarta Servlet technology defines HTTP-specific servlet classes. 6 | 7 | The `jakarta.servlet` and `jakarta.servlet.http` packages provide interfaces and classes for writing servlets. 8 | All servlets must implement the `Servlet` interface, which defines lifecycle methods. 9 | When implementing a generic service, you can use or extend the `GenericServlet` class provided with the Jakarta Servlet API. 10 | The `HttpServlet` class provides methods, such as `doGet` and `doPost`, for handling HTTP-specific services. 11 | -------------------------------------------------------------------------------- /src/main/asciidoc/servlets/servlets004.adoc: -------------------------------------------------------------------------------- 1 | == Creating and Initializing a Servlet 2 | 3 | Use the `@WebServlet` annotation to define a servlet component in a web application. 4 | This annotation is specified on a class and contains metadata about the servlet being declared. 5 | The annotated servlet must specify at least one URL pattern. 6 | This is done by using the `urlPatterns` or `value` attribute on the annotation. 7 | All other attributes are optional, with default settings. 8 | Use the `value` attribute when the only attribute on the annotation is the URL pattern; otherwise, use the `urlPatterns` attribute when other attributes are also used. 9 | 10 | Classes annotated with `@WebServlet` must extend the `jakarta.servlet.http.HttpServlet` class. 11 | For example, the following code snippet defines a servlet with the URL pattern `/report`: 12 | 13 | [source,java] 14 | ---- 15 | import jakarta.servlet.annotation.WebServlet; 16 | import jakarta.servlet.http.HttpServlet; 17 | 18 | @WebServlet("/report") 19 | public class MoodServlet extends HttpServlet { 20 | ... 21 | } 22 | ---- 23 | 24 | The web container initializes a servlet after loading and instantiating the servlet class and before delivering requests from clients. 25 | To customize this process to allow the servlet to read persistent configuration data, initialize resources, and perform any other one-time activities, you can either override the `init` method of the `Servlet` interface or specify the `initParams` attribute of the `@WebServlet` annotation. 26 | The `initParams` attribute contains a `@WebInitParam` annotation. 27 | If it cannot complete its initialization process, a servlet throws an `UnavailableException`. 28 | 29 | Use an initialization parameter to provide data needed by a particular servlet. 30 | By contrast, a context parameter provides data that is available to all components of a web application. 31 | -------------------------------------------------------------------------------- /src/main/asciidoc/servlets/servlets008.adoc: -------------------------------------------------------------------------------- 1 | == Accessing the Web Context 2 | 3 | The context in which web components execute is an object that implements the `ServletContext` interface. 4 | You retrieve the web context by using the `getServletContext` method. 5 | The web context provides methods for accessing 6 | 7 | * Initialization parameters 8 | 9 | * Resources associated with the web context 10 | 11 | * Object-valued attributes 12 | 13 | * Logging capabilities 14 | 15 | The counter's access methods are synchronized to prevent incompatible operations by servlets that are running concurrently. 16 | A filter retrieves the counter object by using the context's `getAttribute` method. 17 | The incremented value of the counter is recorded in the log. 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/servlets/servlets014a.adoc: -------------------------------------------------------------------------------- 1 | == Server Push 2 | 3 | Server push is the ability of the server to anticipate what will be needed by the client in advance of the client's request. 4 | It lets the server pre-populate the browser's cache in advance of the browser asking for the resource to put in the cache. 5 | 6 | Server push is the most visible of the improvements in HTTP/2 to appear in the servlet API. 7 | All of the new features in HTTP/2, including server push, are aimed at improving the performance of the web browsing experience. 8 | 9 | Server push derives its contribution to improved browser performance from the fact that servers know what additional assets (such as images, stylesheets, and scripts) go along with initial requests. 10 | For example, servers might know that whenever a browser requests `index.html`, it will shortly thereafter request `header.gif`, `footer.gif`, and `style.css`. 11 | Servers can preemptively start sending the bytes of these assets along with the bytes of the `index.html`. 12 | 13 | To use server push, obtain a reference to a `PushBuilder` from an `HttpServletRequest`, edit the builder as desired, then call `push()`. 14 | See the https://jakarta.ee/specifications/platform/9/apidocs/[javadoc^] for the class `jakarta.servlet.http.PushBuilder` and the method `jakarta.servlet.http.HttpServletRequest.newPushBuilder()`. 15 | -------------------------------------------------------------------------------- /src/main/asciidoc/servlets/servlets014b.adoc: -------------------------------------------------------------------------------- 1 | == HTTP Trailer 2 | 3 | HTTP trailer is a collection of a special type of HTTP headers that comes after the response body. 4 | The trailer response header allows the sender to include additional fields at the end of chunked messages in order to supply metadata that might be dynamically generated while the message body is sent, such as a message integrity check, digital signature, or post-processing status. 5 | 6 | If trailer headers are ready for reading, `isTrailerFieldsReady()` will return `true`. 7 | Then a servlet can read trailer headers of the HTTP request using the `getTrailerFields` method of the `HttpServletRequest` interface. 8 | If trailer headers are not ready for reading, `isTrailerFieldsReady()` returns `false` and will cause an `IllegalStateException`. 9 | 10 | A servlet can write trailer headers to the response by providing a supplier to the `setTrailerFields()` method of the `HttpServletResponse` interface. 11 | The following headers and types of headers must _not_ be included in the set of keys in the map passed to `setTrailerFields()`: `Transfer-Encoding`, `Content-Length`, `Host`, controls and conditional headers, authentication headers, `Content-Encoding`, `Content-Type`, `Content-Range`, and `Trailer`. 12 | When sending response trailers, you must include a regular header, called `Trailer`, whose value is a comma-separated list of all the keys in the map that is supplied to the `setTrailerFields()` method. 13 | The value of the `Trailer` header lets the client know what trailers to expect. 14 | 15 | The supplier of the trailer headers can be obtained by accessing the `getTrailerFields()` method of the `HttpServletResponse` interface. 16 | 17 | See the https://jakarta.ee/specifications/platform/9/apidocs/[javadoc^] for `getTrailerFields()` and `isTrailerFieldsReady()` in `HttpServletRequest`, and `getTrailerFields()` and `setTrailerFields()` in `HttpServletResponse`. 18 | -------------------------------------------------------------------------------- /src/main/asciidoc/servlets/servlets018.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Jakarta Servlet Technology 2 | 3 | For more information on Jakarta Servlet technology, see the Jakarta Servlet 5.0 specification at https://jakarta.ee/specifications/servlet/5.0/[^]. 4 | -------------------------------------------------------------------------------- /src/main/asciidoc/title.adoc: -------------------------------------------------------------------------------- 1 | [subs="normal"] 2 | ---- 3 | {doctitle} 4 | 5 | Version: {revnumber} 6 | 7 | Status: {revremark} 8 | 9 | Release: {revdate} 10 | ---- 11 | 12 | Copyright (C) 2017, 2021 Oracle and/or its affiliates. All rights reserved. 13 | 14 | This program and the accompanying materials are made available under the terms of the Eclipse Public License v. 2.0, which is available at https://www.eclipse.org/legal/epl-2.0[^]. 15 | 16 | SPDX-License-Identifier: EPL-2.0 17 | 18 | Oracle and Java are registered trademarks of Oracle and/or its affiliates. 19 | Other names may be trademarks of their respective owners. 20 | 21 | Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. 22 | All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. 23 | AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. 24 | UNIX is a registered trademark of The Open Group. 25 | -------------------------------------------------------------------------------- /src/main/asciidoc/transactions/transactions.adoc: -------------------------------------------------------------------------------- 1 | = Transactions 2 | 3 | This chapter describes types of transactions and how they are managed in different applications. 4 | 5 | include::transactions001.adoc[] 6 | 7 | include::transactions002.adoc[] 8 | 9 | include::transactions003.adoc[] 10 | 11 | include::transactions004.adoc[] 12 | 13 | include::transactions005.adoc[] 14 | 15 | include::transactions006.adoc[] 16 | 17 | include::transactions007.adoc[] 18 | 19 | include::transactions008.adoc[] 20 | 21 | include::transactions009.adoc[] 22 | -------------------------------------------------------------------------------- /src/main/asciidoc/transactions/transactions001.adoc: -------------------------------------------------------------------------------- 1 | == Overview of Transactions 2 | 3 | A typical enterprise application accesses and stores information in one or more databases. 4 | Because this information is critical for business operations, it must be accurate, current, and reliable. 5 | Data integrity would be lost if multiple programs were allowed to update the same information simultaneously or if a system that failed while processing a business transaction were to leave the affected data only partially updated. 6 | By preventing both of these scenarios, software transactions ensure data integrity. 7 | Transactions control the concurrent access of data by multiple programs. 8 | In the event of a system failure, transactions make sure that after recovery, the data will be in a consistent state. 9 | -------------------------------------------------------------------------------- /src/main/asciidoc/transactions/transactions002.adoc: -------------------------------------------------------------------------------- 1 | == Transactions in Jakarta EE Applications 2 | 3 | In a Jakarta EE application, a transaction is a series of actions that must all complete successfully, or else all the changes in each action are backed out. 4 | Transactions end in either a commit or a rollback. 5 | 6 | Jakarta Transactions allows applications to access transactions in a manner that is independent of specific implementations. 7 | Jakarta Transactions specifies standard Java interfaces between a transaction manager and the parties involved in a distributed transaction system: the transactional application, the Jakarta EE server, and the manager that controls access to the shared resources affected by the transactions. 8 | 9 | Jakarta Transactions defines the `UserTransaction` interface that applications use to start, commit, or roll back transactions. 10 | Application components get a `UserTransaction` object through a JNDI lookup by using the name `java:comp/UserTransaction` or by requesting injection of a `UserTransaction` object. 11 | An application server uses a number of Jakarta Transactions defined interfaces to communicate with a transaction manager; a transaction manager uses Jakarta Transactions defined interfaces to interact with a resource manager. 12 | 13 | The Jakarta Transactions 2.0 specification is available at https://jakarta.ee/specifications/transactions/2.0/[^]. 14 | -------------------------------------------------------------------------------- /src/main/asciidoc/transactions/transactions003.adoc: -------------------------------------------------------------------------------- 1 | == What Is a Transaction? 2 | 3 | To emulate a business transaction, a program may need to perform several steps. 4 | A financial program, for example, might transfer funds from a checking account to a savings account by using the steps listed in the following pseudocode: 5 | 6 | ---- 7 | begin transaction 8 | debit checking account 9 | credit savings account 10 | update history log 11 | commit transaction 12 | ---- 13 | 14 | Either all or none of the three steps must complete. 15 | Otherwise, data integrity is lost. 16 | Because the steps within a transaction are a unified whole, a transaction is often defined as an indivisible unit of work. 17 | 18 | A transaction can end in two ways: with a commit or with a rollback. 19 | When a transaction commits, the data modifications made by its statements are saved. 20 | If a statement within a transaction fails, the transaction rolls back, undoing the effects of all statements in the transaction. 21 | In the pseudocode, for example, if a disk drive were to crash during the `credit` step, the transaction would roll back and undo the data modifications made by the `debit` statement. 22 | Although the transaction fails, data integrity would be intact because the accounts still balance. 23 | 24 | In the preceding pseudocode, the `begin` and `commit` statements mark the boundaries of the transaction. 25 | When designing an enterprise bean, you determine how the boundaries are set by specifying either container-managed or bean-managed transactions. 26 | -------------------------------------------------------------------------------- /src/main/asciidoc/transactions/transactions006.adoc: -------------------------------------------------------------------------------- 1 | == Transaction Timeouts 2 | 3 | For container-managed transactions, you can use the Administration Console to configure the transaction timeout interval. 4 | See <>. 5 | 6 | For enterprise beans with bean-managed Jakarta transactions, you invoke the `setTransactionTimeout` method of the `UserTransaction` interface. 7 | 8 | === To Set a Transaction Timeout 9 | 10 | . In the Administration Console, expand the Configurations node, then expand the server-config node and select Transaction Service. 11 | 12 | . On the Transaction Service page, set the value of the Transaction Timeout field to the value of your choice (for example, 5). 13 | + 14 | With this setting, if the transaction has not completed within 5 seconds, the enterprise bean container rolls it back. 15 | + 16 | The default value is 0, meaning that the transaction will not time out. 17 | 18 | . Click Save. 19 | -------------------------------------------------------------------------------- /src/main/asciidoc/transactions/transactions007.adoc: -------------------------------------------------------------------------------- 1 | == Updating Multiple Databases 2 | 3 | The Jakarta EE transaction manager controls all enterprise bean transactions except for bean-managed JDBC transactions. 4 | The Jakarta EE transaction manager allows an enterprise bean to update multiple databases within a transaction. 5 | <> and <> show two scenarios for updating multiple databases in a single transaction. 6 | 7 | In <>, the client invokes a business method in `Bean-A`. 8 | The business method begins a transaction, updates Database X, updates Database Y, and invokes a business method in `Bean-B`. 9 | The second business method updates Database Z and returns control to the business method in `Bean-A`, which commits the transaction. 10 | All three database updates occur in the same transaction. 11 | 12 | In <>, the client calls a business method in `Bean-A`, which begins a transaction and updates Database X. 13 | Then `Bean-A` invokes a method in `Bean-B`, which resides in a remote Jakarta EE server. 14 | The method in `Bean-B` updates Database Y. 15 | The transaction managers of the Jakarta EE servers ensure that both databases are updated in the same transaction. 16 | 17 | [[updating-multiple-databases-2]] 18 | .Updating Multiple Databases 19 | image::jakartaeett_dt_051.svg["A diagram showing Bean-A updating databases X and Y, and Bean-B updating database Z."] 20 | 21 | [[updating-multiple-databases-across-jakarta-ee-servers]] 22 | .Updating Multiple Databases Across Jakarta EE Servers 23 | image::jakartaeett_dt_052.svg["A diagram showing Bean-A on one Jakarta EE server updating database X, and Bean-B on another Jakarta EE server updating database Y."] 24 | -------------------------------------------------------------------------------- /src/main/asciidoc/transactions/transactions008.adoc: -------------------------------------------------------------------------------- 1 | == Transactions in Web Components 2 | 3 | You can demarcate a transaction in a web component by using either the `java.sql.Connection` or the `jakarta.transaction.UserTransaction` interface. 4 | These are the same interfaces that a session bean with bean-managed transactions can use. 5 | Transactions demarcated with the `UserTransaction` interface are discussed in <>. 6 | -------------------------------------------------------------------------------- /src/main/asciidoc/transactions/transactions009.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Transactions 2 | 3 | For more information about transactions, see the Jakarta Transactions 2.0 specification at https://jakarta.ee/specifications/transactions/2.0/[^]. 4 | -------------------------------------------------------------------------------- /src/main/asciidoc/usingexamples/usingexamples.adoc: -------------------------------------------------------------------------------- 1 | = Using the Tutorial Examples 2 | 3 | This chapter tells you everything you need to know to install, build, and run the tutorial examples. 4 | 5 | For additional samples, see the GlassFish samples at https://github.com/eclipse-ee4j/glassfish-samples/tree/master/ws/jakartaee9 6 | 7 | include::usingexamples001.adoc[] 8 | 9 | include::usingexamples002.adoc[] 10 | 11 | include::usingexamples003.adoc[] 12 | 13 | include::usingexamples004.adoc[] 14 | 15 | include::usingexamples005.adoc[] 16 | 17 | include::usingexamples006.adoc[] 18 | 19 | include::usingexamples007.adoc[] 20 | 21 | include::usingexamples008.adoc[] 22 | 23 | include::usingexamples009.adoc[] 24 | -------------------------------------------------------------------------------- /src/main/asciidoc/usingexamples/usingexamples002.adoc: -------------------------------------------------------------------------------- 1 | == Starting and Stopping GlassFish Server 2 | 3 | You can start and stop GlassFish Server using either NetBeans IDE or the command line. 4 | 5 | === To Start GlassFish Server Using NetBeans IDE 6 | 7 | . Click the *Services* tab. 8 | 9 | . Expand *Servers*. 10 | 11 | . Right-click the *GlassFish Server instance* and select *Start*. 12 | 13 | === To Stop GlassFish Server Using NetBeans IDE 14 | 15 | To stop GlassFish Server using NetBeans IDE, right-click the *GlassFish Server instance* and select *Stop*. 16 | 17 | === To Start GlassFish Server Using the Command Line 18 | 19 | To start GlassFish Server from the command line, open a terminal window or command prompt and execute the following: 20 | 21 | [source,shell] 22 | ---- 23 | asadmin start-domain --verbose 24 | ---- 25 | 26 | A domain is a set of one or more GlassFish Server instances managed by one administration server. 27 | The following elements are associated with a domain: 28 | 29 | * The GlassFish Server port number: The default is 8080. 30 | 31 | * The administration server's port number: The default is 4848. 32 | 33 | * An administration user name and password: The default user name is `admin`, and by default no password is required. 34 | 35 | You specify these values when you install GlassFish Server. 36 | The examples in this tutorial assume that you chose the default ports as well as the default user name and lack of password. 37 | 38 | With no arguments, the `start-domain` command initiates the default domain, which is `domain1`. 39 | The `--verbose` flag causes all logging and debugging output to appear on the terminal window or command prompt. 40 | The output also goes into the server log, which is located in `_domain-dir_/logs/server.log`. 41 | 42 | === To Stop GlassFish Server Using the Command Line 43 | 44 | To stop GlassFish Server, open a terminal window or command prompt and execute: 45 | 46 | [source,shell] 47 | ---- 48 | asadmin stop-domain domain1 49 | ---- 50 | -------------------------------------------------------------------------------- /src/main/asciidoc/usingexamples/usingexamples003.adoc: -------------------------------------------------------------------------------- 1 | == Starting the Administration Console 2 | 3 | To administer GlassFish Server and manage users, resources, and Jakarta EE applications, use the Administration Console tool. 4 | GlassFish Server must be running before you invoke the Administration Console. 5 | To start the Administration Console, open a browser at http://localhost:4848/[^]. 6 | 7 | === To Start the Administration Console Using NetBeans IDE 8 | 9 | . Click the *Services* tab. 10 | 11 | . Expand *Servers*. 12 | 13 | . Right-click the *GlassFish Server instance* and select *View Domain Admin Console*. 14 | 15 | [NOTE] 16 | NetBeans IDE uses your default web browser to open the Administration Console. 17 | -------------------------------------------------------------------------------- /src/main/asciidoc/usingexamples/usingexamples004.adoc: -------------------------------------------------------------------------------- 1 | == Starting and Stopping Apache Derby 2 | 3 | GlassFish Server includes Apache Derby. 4 | 5 | === To Start Derby Using Command Line 6 | 7 | To start Derby from the command line, open a terminal window or command prompt, change to the `_as-install_/bin` directory, and execute: 8 | 9 | [source,shell] 10 | ---- 11 | asadmin start-database 12 | ---- 13 | 14 | === To Stop Derby Using Command Line 15 | 16 | To stop Derby from the command line, open a terminal window or command prompt, change to the `_as-install_/bin` directory, and execute: 17 | 18 | [source,shell] 19 | ---- 20 | asadmin stop-database 21 | ---- 22 | 23 | For information about Apache Derby included with GlassFish Server, see the Release Notes that are located in the `_as-install_/javadb/` directory. 24 | 25 | === To Start Derby Using NetBeans IDE 26 | 27 | When you start GlassFish Server using NetBeans IDE, the database server starts automatically. 28 | If you ever need to start the server manually, however, follow these steps. 29 | 30 | . Click the *Services* tab. 31 | 32 | . Expand *Databases*. 33 | 34 | . Right-click *Java DB* and select *Start Server*. 35 | 36 | === To Stop Derby Using NetBeans IDE 37 | 38 | To stop the database using NetBeans IDE, right-click *Java DB* and select *Stop Server*. 39 | -------------------------------------------------------------------------------- /src/main/asciidoc/usingexamples/usingexamples005.adoc: -------------------------------------------------------------------------------- 1 | == Building the Examples 2 | 3 | The tutorial examples are distributed with a configuration file for either NetBeans IDE or Maven. 4 | Either NetBeans IDE or Maven may be used to build, package, deploy, and run the examples. 5 | Directions for building the examples are provided in each chapter. 6 | -------------------------------------------------------------------------------- /src/main/asciidoc/usingexamples/usingexamples006.adoc: -------------------------------------------------------------------------------- 1 | == Tutorial Example Directory Structure 2 | 3 | To facilitate iterative development and keep application source files separate from compiled files, the tutorial examples use the Maven application directory structure. 4 | 5 | Each application module has the following structure: 6 | 7 | * `pom.xml`: Maven build file 8 | 9 | * `src/main/java`: Java source files for the module 10 | 11 | * `src/main/resources`: configuration files for the module, with the exception of web applications 12 | 13 | * `src/main/webapp`: web pages, style sheets, tag files, and images (web applications only) 14 | 15 | * `src/main/webapp/WEB-INF`: configuration files for web applications (web applications only) 16 | 17 | When an example has multiple application modules packaged into an EAR file, its submodule directories use the following naming conventions: 18 | 19 | * _example-name_``-app-client``: application clients 20 | 21 | * _example-name_``-ejb``: enterprise bean JAR files 22 | 23 | * _example-name_``-war``: web applications 24 | 25 | * _example-name_``-ear``: enterprise applications 26 | 27 | * _example-name_``-common``: library JAR containing components, classes, and files used by other modules 28 | 29 | The Maven build files (`pom.xml`) distributed with the examples contain goals to compile and assemble the application into the `target` directory and deploy the archive to GlassFish Server. 30 | -------------------------------------------------------------------------------- /src/main/asciidoc/usingexamples/usingexamples007.adoc: -------------------------------------------------------------------------------- 1 | == Jakarta EE Maven Archetypes in the Tutorial 2 | 3 | Some of the chapters have instructions on how to build an example application using Maven archetypes. 4 | Archetypes are templates for generating a particular Maven project. 5 | The Tutorial includes several Maven archetypes for generating Jakarta EE projects. 6 | 7 | === Installing the Tutorial Archetypes 8 | 9 | You must install the included Maven archetypes into your local Maven repository before you can create new projects based on the archetypes. 10 | You can install the archetypes using NetBeans IDE or Maven. 11 | 12 | ==== Installing the Tutorial Archetypes Using NetBeans IDE 13 | 14 | . From the *File* menu, choose *Open Project*. 15 | 16 | . In the Open Project dialog box, navigate to: + 17 | ---- 18 | tut-install/examples 19 | ---- 20 | 21 | . Select the `archetypes` folder. 22 | 23 | . Click *Open Project*. 24 | 25 | . In the *Projects* tab, right-click the `archetypes` project and select *Build*. 26 | 27 | ==== Installing the Tutorial Archetypes Using Maven 28 | 29 | . In a terminal window, go to: + 30 | ---- 31 | tut-install/examples/archetypes/ 32 | ---- 33 | 34 | . Enter the following command: + 35 | [source,shell] 36 | ---- 37 | mvn install 38 | ---- 39 | -------------------------------------------------------------------------------- /src/main/asciidoc/usingexamples/usingexamples008.adoc: -------------------------------------------------------------------------------- 1 | //// 2 | [NOTE] 3 | Glassfish no longer ships with Update Tool 4 | //// 5 | //// 6 | == Getting the Latest Updates to the Tutorial 7 | 8 | Check for any updates to the tutorial by using the Update Tool included with the Jakarta EE SDK. 9 | 10 | === To Update the Tutorial Using NetBeans IDE 11 | 12 | . Open the *Services* tab in NetBeans IDE and expand *Servers*. 13 | 14 | . Right-click the GlassFish Server instance and select *View Domain Update Center* to display the Update Tool. 15 | 16 | . Select *Available Updates* in the tree to display a list of updated packages. 17 | 18 | . Look for updates to the Jakarta EE Tutorial (jakartaee-tutorial) package. 19 | 20 | . If there is an updated version of the Tutorial, select *Jakarta EE Tutorial* (`jakartaee-tutorial`) and click *Install*. 21 | 22 | === To Update the Tutorial Using the Command Line 23 | 24 | . Open a terminal window and enter the following command to display the Update Tool: + 25 | ---- 26 | updatetool 27 | ---- 28 | 29 | . Select *Available Updates* in the tree to display a list of updated packages. 30 | 31 | . Look for updates to the Jakarta EE Tutorial (`jakartaee-tutorial`) package. 32 | 33 | . If there is an updated version of the tutorial, select *Jakarta EE Tutorial* (`jakartaee-tutorial`) and click *Install*. 34 | 35 | //// -------------------------------------------------------------------------------- /src/main/asciidoc/webapp/webapp.adoc: -------------------------------------------------------------------------------- 1 | = Getting Started with Web Applications 2 | 3 | This chapter introduces web applications, which typically use Jakarta Faces technology and/or Jakarta Servlet technology. 4 | 5 | include::webapp001.adoc[] 6 | 7 | include::webapp002.adoc[] 8 | 9 | include::webapp003.adoc[] 10 | 11 | include::webapp004.adoc[] 12 | 13 | include::webapp005.adoc[] 14 | 15 | include::webapp006.adoc[] 16 | 17 | -------------------------------------------------------------------------------- /src/main/asciidoc/webapp/webapp002.adoc: -------------------------------------------------------------------------------- 1 | == Web Application Lifecycle 2 | 3 | A web application consists of web components; static resource files, such as images and cascading style sheets (CSS); and helper classes and libraries. 4 | The web container provides many supporting services that enhance the capabilities of web components and make them easier to develop. 5 | However, because a web application must take these services into account, the process for creating and running a web application is different from that of traditional stand-alone Java classes. 6 | 7 | The process for creating, deploying, and executing a web application can be summarized as follows: 8 | 9 | . Develop the web component code. 10 | 11 | . Develop the web application deployment descriptor, if necessary. 12 | 13 | . Compile the web application components and helper classes referenced by the components. 14 | 15 | . Optionally, package the application into a deployable unit. 16 | 17 | . Deploy the application into a web container. 18 | 19 | . Access a URL that references the web application. 20 | 21 | Developing web component code is covered in the later chapters. 22 | Steps 2 through 6 are expanded on in the following sections and illustrated with a Hello, World–style, presentation-oriented application. 23 | This application allows a user to enter a name into an HTML form and then displays a greeting after the name is submitted. 24 | 25 | The Hello application contains two web components that generate the greeting and the response. 26 | This chapter discusses the following simple applications: 27 | 28 | * `hello1`, a Jakarta Faces technology–based application that uses two XHTML pages and a managed bean 29 | 30 | * `hello2`, a servlet-based web application in which the components are implemented by two servlet classes 31 | 32 | The applications are used to illustrate tasks involved in packaging, deploying, configuring, and running an application that contains web components. 33 | -------------------------------------------------------------------------------- /src/main/asciidoc/webapp/webapp006.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about Web Applications 2 | 3 | For more information on web applications, see 4 | 5 | * Jakarta Faces 3.0 specification: + 6 | https://jakarta.ee/specifications/faces/3.0/[^] 7 | 8 | * Jakarta Servlet 5.0 specification: + 9 | https://jakarta.ee/specifications/servlet/5.0/[^] 10 | -------------------------------------------------------------------------------- /src/main/asciidoc/webi18n/webi18n.adoc: -------------------------------------------------------------------------------- 1 | = Internationalizing and Localizing Web Applications 2 | 3 | The process of preparing an application to support more than one language and data format is called internationalization. 4 | Localization is the process of adapting an internationalized application to support a specific region or locale. 5 | Examples of locale-dependent information include messages and user interface labels, character sets and encoding, and date and currency formats. 6 | Although all client user interfaces should be internationalized and localized, it is particularly important for web applications because of the global nature of the web. 7 | 8 | include::webi18n001.adoc[] 9 | 10 | include::webi18n002.adoc[] 11 | 12 | include::webi18n003.adoc[] 13 | 14 | include::webi18n004.adoc[] 15 | -------------------------------------------------------------------------------- /src/main/asciidoc/webi18n/webi18n001.adoc: -------------------------------------------------------------------------------- 1 | == Java Platform Localization Classes 2 | 3 | In the Java platform, `java.util.Locale` (https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html[^]) represents a specific geographical, political, or cultural region. 4 | The string representation of a locale consists of the international standard two-character abbreviation for language and country and an optional variant, all separated by underscore (`_`) characters. 5 | Examples of locale strings include `fr` (French), `de_CH` (Swiss German), and `en_US_POSIX` (English on a POSIX-compliant platform). 6 | 7 | Locale-sensitive data is stored in a `java.util.ResourceBundle` (https://docs.oracle.com/javase/8/docs/api/java/util/ResourceBundle.html[^]). 8 | A resource bundle contains key-value pairs, where the keys uniquely identify a locale-specific object in the bundle. 9 | A resource bundle can be backed by a text file (properties resource bundle) or a class (list resource bundle) containing the pairs. 10 | You construct a resource bundle instance by appending a locale string representation to a base name. 11 | 12 | The Duke's Bookstore application (see xref:dukes-bookstore-case-study-example[xrefstyle=full]) contains resource bundles with the base name `messages.properties` for the locales `de` (German), `es` (Spanish), and `fr` (French). 13 | The default locale, `en` (English), which is specified in the `faces-config.xml` file, uses the resource bundle with the base name, `messages.properties`. 14 | 15 | For more details on internationalization and localization in the Java platform, see https://docs.oracle.com/javase/tutorial/i18n/index.html[^]. 16 | -------------------------------------------------------------------------------- /src/main/asciidoc/webi18n/webi18n003.adoc: -------------------------------------------------------------------------------- 1 | == Date and Number Formatting 2 | 3 | Java programs use the `DateFormat.getDateInstance(int, locale)` method to parse and format dates in a locale-sensitive manner. 4 | Java programs use the `NumberFormat.get__XXX__Instance(locale)` method, where _XXX_ can be `Currency`, `Number`, or `Percent`, to parse and format numerical values in a locale-sensitive manner. 5 | 6 | An application can use date/time and number converters to format dates and numbers in a locale-sensitive manner. 7 | For example, a shipping date could be converted as follows: 8 | 9 | [source,xml] 10 | ---- 11 | 12 | 13 | 14 | ---- 15 | 16 | For information on Jakarta Faces converters, see <>. 17 | -------------------------------------------------------------------------------- /src/main/asciidoc/webservices-intro/webservices-intro.adoc: -------------------------------------------------------------------------------- 1 | = Introduction to Web Services 2 | 3 | This part of the tutorial discusses Jakarta EE web services technologies. 4 | These technologies include Jakarta XML Web Services and Jakarta RESTful Web Services. 5 | 6 | include::webservices-intro001.adoc[] 7 | 8 | include::webservices-intro002.adoc[] 9 | 10 | include::webservices-intro003.adoc[] 11 | -------------------------------------------------------------------------------- /src/main/asciidoc/webservices-intro/webservices-intro001.adoc: -------------------------------------------------------------------------------- 1 | == What Are Web Services? 2 | 3 | Web services are client and server applications that communicate over the World Wide Web's (WWW) HyperText Transfer Protocol (HTTP). 4 | As described by the World Wide Web Consortium (W3C), web services provide a standard means of interoperating between software applications running on a variety of platforms and frameworks. 5 | Web services are characterized by their great interoperability and extensibility as well as their machine-processable descriptions, thanks to the use of XML. 6 | Web services can be combined in a loosely coupled way to achieve complex operations. 7 | Programs providing simple services can interact with each other to deliver sophisticated added-value services. 8 | -------------------------------------------------------------------------------- /src/main/asciidoc/webservices-intro/webservices-intro003.adoc: -------------------------------------------------------------------------------- 1 | == Deciding Which Type of Web Service to Use 2 | 3 | Basically, you want to use RESTful web services for integration over the web and big web services in enterprise application–integration scenarios that have advanced quality-of-service (QoS) requirements. 4 | 5 | Jakarta XML Web Services:: Addresses advanced QoS requirements that commonly occur in enterprise computing. 6 | When compared to Jakarta RESTful Web Services, XML Web Services makes it easier to support the WS-* set of protocols, which provide standards for security and reliability, among other things, and interoperate with other WS-* conforming clients and servers. 7 | 8 | Jakarta RESTful Web Services:: Makes it easier to write web applications that apply some or all of the constraints of the REST style to induce desirable properties in the application, such as loose coupling (evolving the server is easier without breaking existing clients), scalability (start small and grow), and architectural simplicity (use off-the-shelf components, such as proxies or HTTP routers). 9 | You would choose to use Jakarta RESTful Web Services for your web application because it is easier for many types of clients to consume RESTful web services while enabling the server side to evolve and scale. 10 | Clients can choose to consume some or all aspects of the service and mash it up with other web-based services. 11 | -------------------------------------------------------------------------------- /src/main/asciidoc/websocket/websocket.adoc: -------------------------------------------------------------------------------- 1 | = Jakarta WebSocket 2 | 3 | This chapter describes Jakarta WebSocket, which provides support for creating WebSocket applications. 4 | WebSocket is an application protocol that provides full-duplex communications between two peers over the TCP protocol. 5 | 6 | include::websocket001.adoc[] 7 | 8 | include::websocket002.adoc[] 9 | 10 | include::websocket003.adoc[] 11 | 12 | include::websocket004.adoc[] 13 | 14 | include::websocket005.adoc[] 15 | 16 | include::websocket006.adoc[] 17 | 18 | include::websocket007.adoc[] 19 | 20 | include::websocket008.adoc[] 21 | 22 | include::websocket009.adoc[] 23 | 24 | include::websocket010.adoc[] 25 | 26 | include::websocket011.adoc[] 27 | 28 | include::websocket012.adoc[] 29 | 30 | include::websocket013.adoc[] 31 | -------------------------------------------------------------------------------- /src/main/asciidoc/websocket/websocket003.adoc: -------------------------------------------------------------------------------- 1 | == Programmatic Endpoints 2 | 3 | The following example shows how to create an endpoint by extending the `Endpoint` class: 4 | 5 | [source,java] 6 | ---- 7 | public class EchoEndpoint extends Endpoint { 8 | @Override 9 | public void onOpen(final Session session, EndpointConfig config) { 10 | session.addMessageHandler(new MessageHandler.Whole() { 11 | @Override 12 | public void onMessage(String msg) { 13 | try { 14 | session.getBasicRemote().sendText(msg); 15 | } catch (IOException e) { ... } 16 | } 17 | }); 18 | } 19 | } 20 | ---- 21 | 22 | This endpoint echoes every message received. 23 | The `Endpoint` class defines three lifecycle methods: `onOpen`, `onClose`, and `onError`. 24 | The `EchoEndpoint` class implements the `onOpen` method, which is the only abstract method in the `Endpoint` class. 25 | 26 | The `Session` parameter represents a conversation between this endpoint and the remote endpoint. 27 | The `addMessageHandler` method registers message handlers, and the `getBasicRemote` method returns an object that represents the remote endpoint. 28 | The `Session` interface is covered in detail in the rest of this chapter. 29 | 30 | The message handler is implemented as an anonymous inner class. 31 | The `onMessage` method of the message handler is invoked when the endpoint receives a text message. 32 | 33 | To deploy this programmatic endpoint, use the following code in your Jakarta EE application: 34 | 35 | [source,java] 36 | ---- 37 | ServerEndpointConfig.Builder.create(EchoEndpoint.class, "/echo").build(); 38 | ---- 39 | 40 | When you deploy your application, the endpoint is available at `ws://://echo`; for example, `ws://localhost:8080/echoapp/echo`. 41 | -------------------------------------------------------------------------------- /src/main/asciidoc/websocket/websocket006.adoc: -------------------------------------------------------------------------------- 1 | == Maintaining Client State 2 | 3 | Because the container creates an instance of the endpoint class for every connection, you can define and use instance variables to store client state information. 4 | In addition, the `Session.getUserProperties` method provides a modifiable map to store user properties. 5 | For example, the following endpoint replies to incoming text messages with the contents of the previous message from each client: 6 | 7 | [source,java] 8 | ---- 9 | @ServerEndpoint("/delayedecho") 10 | public class DelayedEchoEndpoint { 11 | @OnOpen 12 | public void open(Session session) { 13 | session.getUserProperties().put("previousMsg", " "); 14 | } 15 | @OnMessage 16 | public void message(Session session, String msg) { 17 | String prev = (String) session.getUserProperties() 18 | .get("previousMsg"); 19 | session.getUserProperties().put("previousMsg", msg); 20 | try { 21 | session.getBasicRemote().sendText(prev); 22 | } catch (IOException e) { ... } 23 | } 24 | } 25 | ---- 26 | 27 | To store information common to all connected clients, you can use class (static) variables; however, you are responsible for ensuring thread-safe access to them. 28 | -------------------------------------------------------------------------------- /src/main/asciidoc/websocket/websocket008.adoc: -------------------------------------------------------------------------------- 1 | == Path Parameters 2 | 3 | The `ServerEndpoint` annotation enables you to use URI templates to specify parts of an endpoint deployment URI as application parameters. 4 | For example, consider this endpoint: 5 | 6 | [source,java] 7 | ---- 8 | @ServerEndpoint("/chatrooms/{room-name}") 9 | public class ChatEndpoint { 10 | ... 11 | } 12 | ---- 13 | 14 | If the endpoint is deployed inside a web application called `chatapp` at a local Jakarta EE server in port 8080, clients can connect to the endpoint using any of the following URIs: 15 | 16 | ---- 17 | http://localhost:8080/chatapp/chatrooms/currentnews 18 | http://localhost:8080/chatapp/chatrooms/music 19 | http://localhost:8080/chatapp/chatrooms/cars 20 | http://localhost:8080/chatapp/chatrooms/technology 21 | ---- 22 | 23 | Annotated endpoints can receive path parameters as arguments in methods annotated with `@OnOpen`, `@OnMessage`, and `@OnClose`. 24 | In this example, the endpoint uses the parameter in the `@OnOpen` method to determine which chat room the client wants to join: 25 | 26 | [source,java] 27 | ---- 28 | @ServerEndpoint("/chatrooms/{room-name}") 29 | public class ChatEndpoint { 30 | @OnOpen 31 | public void open(Session session, 32 | EndpointConfig c, 33 | @PathParam("room-name") String roomName) { 34 | // Add the client to the chat room of their choice ... 35 | } 36 | } 37 | ---- 38 | 39 | The path parameters used as arguments in these methods can be strings, primitive types, or the corresponding wrapper types. 40 | -------------------------------------------------------------------------------- /src/main/asciidoc/websocket/websocket009.adoc: -------------------------------------------------------------------------------- 1 | == Handling Errors 2 | 3 | To designate a method that handles errors in an annotated WebSocket endpoint, decorate it with `@OnError`: 4 | 5 | [source,java] 6 | ---- 7 | @ServerEndpoint("/testendpoint") 8 | public class TestEndpoint { 9 | ... 10 | @OnError 11 | public void error(Session session, Throwable t) { 12 | t.printStackTrace(); 13 | ... 14 | } 15 | } 16 | ---- 17 | 18 | This method is invoked when there are connection problems, runtime errors from message handlers, or conversion errors when decoding messages. 19 | -------------------------------------------------------------------------------- /src/main/asciidoc/websocket/websocket013.adoc: -------------------------------------------------------------------------------- 1 | == Further Information about WebSocket 2 | 3 | For more information on WebSocket in Jakarta EE, see the Jakarta WebSocket specification: 4 | 5 | https://jakarta.ee/specifications/websocket/2.0/[^] 6 | -------------------------------------------------------------------------------- /tutorial.xml: -------------------------------------------------------------------------------- 1 | 2 | 19 | 20 | 21 | tutorial 22 | 23 | zip 24 | 25 | jakartaee-tutorial 26 | 27 | 28 | target/generated-docs 29 | 30 | 31 | 32 | target/staging 33 | doc 34 | 35 | _config.yml 36 | _layouts/** 37 | assets/** 38 | *.md 39 | 40 | 41 | 42 | 43 | --------------------------------------------------------------------------------